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
336 lines
12 KiB
C++
336 lines
12 KiB
C++
//===--- Markup.h - Markup ------------------------------------------------===//
|
|
//
|
|
// 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
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#include "llvm/ADT/SmallVector.h"
|
|
#include "llvm/Support/ErrorHandling.h"
|
|
#include "swift/AST/Comment.h"
|
|
#include "swift/Markup/LineList.h"
|
|
#include "swift/Markup/Markup.h"
|
|
#include "cmark.h"
|
|
#include "node.h"
|
|
|
|
using namespace llvm;
|
|
using namespace markup;
|
|
struct ParseState {
|
|
cmark_iter *Iter = nullptr;
|
|
cmark_event_type Event = CMARK_EVENT_NONE;
|
|
cmark_node *Node = nullptr;
|
|
|
|
public:
|
|
ParseState() = default;
|
|
ParseState(cmark_iter *Iter, cmark_event_type Event = CMARK_EVENT_NONE,
|
|
cmark_node *Node = nullptr)
|
|
: Iter(Iter), Event(Event), Node(Node) {}
|
|
|
|
ParseState next() const {
|
|
auto I = Iter;
|
|
auto Event = cmark_iter_next(I);
|
|
auto Node = cmark_iter_get_node(I);
|
|
return ParseState(I, Event, Node);
|
|
}
|
|
|
|
cmark_node_type getType() const {
|
|
return cmark_node_get_type(Node);
|
|
}
|
|
};
|
|
|
|
template <typename NodeType>
|
|
struct ParseResult {
|
|
NodeType *Node;
|
|
ParseState State;
|
|
|
|
public:
|
|
operator ParseResult<MarkupASTNode>() {
|
|
return { cast<MarkupASTNode>(Node), State };
|
|
}
|
|
};
|
|
|
|
StringRef getLiteralContent(MarkupContext &MC, LineList &LL, cmark_node *Node) {
|
|
// Literal content nodes never have start/end column line information.
|
|
// It is a floating piece of text that inherits location information from
|
|
// its parent.
|
|
auto Literal = cmark_node_get_literal(Node);
|
|
assert(Literal != nullptr);
|
|
size_t Length = 0;
|
|
switch (cmark_node_get_type(Node)) {
|
|
case CMARK_NODE_CODE_BLOCK:
|
|
Length = Node->as.code.literal.len;
|
|
break;
|
|
default:
|
|
Length = Node->as.literal.len;
|
|
}
|
|
return MC.allocateCopy(StringRef(Literal, Length));
|
|
}
|
|
|
|
ParseResult<MarkupASTNode>
|
|
parseElement(MarkupContext &MC, LineList &LL, ParseState State);
|
|
|
|
ParseState parseChildren(MarkupContext &MC, LineList &LL, ParseState State,
|
|
SmallVectorImpl<MarkupASTNode *> &Children) {
|
|
auto Root = State.Node;
|
|
State = State.next();
|
|
do {
|
|
if (Root == State.Node && State.Event == CMARK_EVENT_EXIT)
|
|
break;
|
|
auto Result = parseElement(MC, LL, State);
|
|
Children.push_back(Result.Node);
|
|
State = Result.State;
|
|
} while (!(Root == State.Node && State.Event == CMARK_EVENT_EXIT));
|
|
return State;
|
|
}
|
|
|
|
ParseResult<Text> parseText(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_TEXT
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { Text::create(MC, getLiteralContent(MC, LL, State.Node)),
|
|
State.next() };
|
|
}
|
|
|
|
ParseResult<BlockQuote> parseBlockQuote(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_BLOCK_QUOTE
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
SmallVector<MarkupASTNode *, 4> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { BlockQuote::create(MC, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<Code> parseCode(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_CODE
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { Code::create(MC, getLiteralContent(MC, LL, State.Node)),
|
|
State.next() };
|
|
}
|
|
|
|
ParseResult<CodeBlock> parseCodeBlock(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_CODE_BLOCK
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { CodeBlock::create(MC, getLiteralContent(MC, LL, State.Node)),
|
|
State.next() };
|
|
}
|
|
|
|
ParseResult<Emphasis> parseEmphasis(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_EMPH
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Emphasis::create(MC, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<Strong> parseStrong(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_STRONG
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Strong::create(MC, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<Header> parseHeader(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_HEADER
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
auto Level = cmark_node_get_header_level(State.Node);
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Header::create(MC, Level, Children), State.next() };
|
|
}
|
|
|
|
ParseResult<HRule> parseHRule(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_HRULE
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { HRule::create(MC), State.next() };
|
|
}
|
|
|
|
ParseResult<HTML> parseHTML(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_HTML
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { HTML::create(MC, getLiteralContent(MC, LL, State.Node)),
|
|
State.next() };
|
|
}
|
|
|
|
ParseResult<InlineHTML> parseInlineHTML(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_INLINE_HTML
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { InlineHTML::create(MC, getLiteralContent(MC, LL, State.Node)),
|
|
State.next() };
|
|
}
|
|
|
|
ParseResult<Image> parseImage(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_IMAGE
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
std::string Destination(cmark_node_get_url(State.Node));
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Image::create(MC, Destination, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<Item> parseItem(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_ITEM
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Item::create(MC, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<LineBreak> parseLineBreak(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_LINEBREAK
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { LineBreak::create(MC), State.next() };
|
|
}
|
|
|
|
ParseResult<SoftBreak> parseSoftBreak(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_SOFTBREAK
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
return { SoftBreak::create(MC), State.next() };
|
|
}
|
|
|
|
ParseResult<Link> parseLink(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_LINK
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
std::string Destination(cmark_node_get_url(State.Node));
|
|
SmallVector<MarkupASTNode *, 2> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Link::create(MC, Destination, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<List> parseList(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_LIST
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
auto ListRoot = State.Node;
|
|
auto IsOrdered = cmark_node_get_list_type(ListRoot) == CMARK_ORDERED_LIST;
|
|
SmallVector<MarkupASTNode *, 3> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { List::create(MC, Children, IsOrdered), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<Paragraph> parseParagraph(MarkupContext &MC, LineList &LL,
|
|
ParseState State) {
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_PARAGRAPH
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
SmallVector<MarkupASTNode *, 3> Children;
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
return { Paragraph::create(MC, Children), ResultState.next() };
|
|
}
|
|
|
|
ParseResult<MarkupASTNode>
|
|
parseElement(MarkupContext &MC, LineList &LL, ParseState State) {
|
|
assert(State.Event == CMARK_EVENT_ENTER);
|
|
auto NodeType = cmark_node_get_type(State.Node);
|
|
switch (NodeType) {
|
|
case CMARK_NODE_DOCUMENT: {
|
|
llvm_unreachable("Markup documents cannot be nested");
|
|
}
|
|
case CMARK_NODE_BLOCK_QUOTE: {
|
|
return parseBlockQuote(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_CODE: {
|
|
return parseCode(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_CODE_BLOCK: {
|
|
return parseCodeBlock(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_EMPH: {
|
|
return parseEmphasis(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_HEADER: {
|
|
return parseHeader(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_HRULE: {
|
|
return parseHRule(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_HTML: {
|
|
return parseHTML(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_IMAGE: {
|
|
return parseImage(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_INLINE_HTML: {
|
|
return parseInlineHTML(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_ITEM: {
|
|
return parseItem(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_LINEBREAK: {
|
|
return parseLineBreak(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_LINK: {
|
|
return parseLink(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_LIST: {
|
|
return parseList(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_PARAGRAPH: {
|
|
return parseParagraph(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_SOFTBREAK: {
|
|
return parseSoftBreak(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_STRONG: {
|
|
return parseStrong(MC, LL, State);
|
|
}
|
|
case CMARK_NODE_TEXT: {
|
|
return parseText(MC, LL, State);
|
|
}
|
|
default: {
|
|
llvm_unreachable("Can't parse a Markup node of type 'None'");
|
|
}
|
|
}
|
|
}
|
|
|
|
Document *llvm::markup::parseDocument(MarkupContext &MC, LineList &LL) {
|
|
auto Comment = LL.str();
|
|
auto CMarkDoc = cmark_parse_document(Comment.c_str(), Comment.size(),
|
|
CMARK_OPT_DEFAULT);
|
|
|
|
if (CMarkDoc == nullptr)
|
|
return nullptr;
|
|
|
|
ParseState State(cmark_iter_new(CMarkDoc));
|
|
// Prime the parser.
|
|
State = State.next();
|
|
SmallVector<MarkupASTNode *, 8> Children;
|
|
assert(cmark_node_get_type(State.Node) == CMARK_NODE_DOCUMENT
|
|
&& State.Event == CMARK_EVENT_ENTER);
|
|
auto ResultState = parseChildren(MC, LL, State, Children);
|
|
assert(State.Node == ResultState.Node
|
|
&& ResultState.Event == CMARK_EVENT_EXIT);
|
|
State = ResultState.next();
|
|
assert(State.Event == CMARK_EVENT_DONE);
|
|
cmark_node_free(CMarkDoc);
|
|
return Document::create(MC, Children);
|
|
}
|