mirror of
https://github.com/apple/swift.git
synced 2025-12-21 12:14:44 +01:00
ca5876a866
Replace ReST-flavored documentation comments with Markdown. rdar://problem/20180412 In addition to full Markdown support, the following extensions are supported. These appear as lists at the top level of the comment's "document". All of these extensions are matched without regard to case. Parameter Outlines ------------------ - Parameters: - x: ... - y: ... Separate Parameters ------------------- - parameter x: ... - parameter y: ... - Note: Parameter documentation may be broken up across the entire comment, with a mix of parameter documentation kinds - they'll be consolidated in the end. Returns ------- - returns: ... The following extensions are also list items at the top level, which will also appear in Xcode QuickHelp as first-class citizens: - Attention: ... - Author: ... - Authors: ... - Bug: ... - Complexity: ... - Copyright: ... - Date: ... - Experiment: ... - Important: ... - Invariant: ... - Note: ... - Postcondition: ... - Precondition: ... - Remark: ... - Remarks: ... - See: ... - Since: ... - Todo: ... - Version: ... - Warning: ... These match most of the extra fields in Doxygen, plus a few more per request. Other changes ------------- - Remove use of rawHTML for all markup AST nodes except for those not representable by the Xcode QuickHelp XSLT - <h>, <hr/>, and of course inline/block HTML itself. - Update the doc comment RNG schema to more accurately reflect Xcode QuickHelp. - Clean up cmark CMake configuration. - Rename "FullComment" to "DocComment" - Update the Swift Standard Documentation (in a follow-up commit) - Update SourceKit for minor changes and link against cmark (in a follow-up commit). Swift SVN r27727
78 lines
1.7 KiB
C++
78 lines
1.7 KiB
C++
//===--- XMLUtils.h - Various XML utility routines ------------------------===//
|
|
//
|
|
// This source file is part of the Swift.org open source project
|
|
//
|
|
// Copyright (c) 2014 - 2015 Apple Inc. and the Swift project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See http://swift.org/LICENSE.txt for license information
|
|
// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef LLVM_MARKUP_XML_UTILS_H
|
|
#define LLVM_MARKUP_XML_UTILS_H
|
|
|
|
#include "llvm/ADT/StringRef.h"
|
|
#include "llvm/Support/raw_ostream.h"
|
|
|
|
namespace llvm {
|
|
namespace markup {
|
|
|
|
// FIXME: copied from Clang's
|
|
// CommentASTToXMLConverter::appendToResultWithXMLEscaping
|
|
static inline void appendWithXMLEscaping(raw_ostream &OS, StringRef S) {
|
|
for (const char C : S) {
|
|
switch (C) {
|
|
case '&':
|
|
OS << "&";
|
|
break;
|
|
case '<':
|
|
OS << "<";
|
|
break;
|
|
case '>':
|
|
OS << ">";
|
|
break;
|
|
case '"':
|
|
OS << """;
|
|
break;
|
|
case '\'':
|
|
OS << "'";
|
|
break;
|
|
default:
|
|
OS << C;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
// FIXME: copied from Clang's
|
|
// CommentASTToXMLConverter::appendToResultWithCDATAEscaping
|
|
static inline void appendWithCDATAEscaping(raw_ostream &OS, StringRef S) {
|
|
if (S.empty())
|
|
return;
|
|
|
|
OS << "<![CDATA[";
|
|
while (!S.empty()) {
|
|
size_t Pos = S.find("]]>");
|
|
if (Pos == 0) {
|
|
OS << "]]]]><![CDATA[>";
|
|
S = S.drop_front(3);
|
|
continue;
|
|
}
|
|
if (Pos == StringRef::npos)
|
|
Pos = S.size();
|
|
|
|
OS << S.substr(0, Pos);
|
|
|
|
S = S.drop_front(Pos);
|
|
}
|
|
OS << "]]>";
|
|
}
|
|
|
|
} // namespace markup
|
|
} // namespace llvm
|
|
|
|
#endif // LLVM_MARKUP_XML_UTILS_H
|
|
|