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
96 lines
2.6 KiB
C++
96 lines
2.6 KiB
C++
//===--- Comment.h - Swift-specific comment parsing -----------------------===//
|
|
//
|
|
// 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 SWIFT_AST_COMMENT_H
|
|
#define SWIFT_AST_COMMENT_H
|
|
|
|
#include "swift/Markup/Markup.h"
|
|
#include "llvm/ADT/Optional.h"
|
|
|
|
namespace swift {
|
|
class Decl;
|
|
class DocComment;
|
|
struct RawComment;
|
|
|
|
class DocComment {
|
|
public:
|
|
struct CommentParts {
|
|
Optional<const llvm::markup::Paragraph *>Brief;
|
|
SmallVector<const llvm::markup::MarkupASTNode *, 4> BodyNodes;
|
|
SmallVector<const llvm::markup::ParamField *, 8> ParamFields;
|
|
Optional<const llvm::markup::ReturnsField *>ReturnsField;
|
|
|
|
bool isEmpty() const {
|
|
return !Brief.hasValue() && !ReturnsField.hasValue() && BodyNodes.empty() && ParamFields.empty();
|
|
}
|
|
};
|
|
|
|
private:
|
|
const Decl *D;
|
|
const llvm::markup::Document *Doc = nullptr;
|
|
const CommentParts Parts;
|
|
|
|
public:
|
|
DocComment(const Decl *D, llvm::markup::Document *Doc,
|
|
CommentParts Parts)
|
|
: D(D), Doc(Doc), Parts(Parts) {}
|
|
|
|
const Decl *getDecl() const { return D; }
|
|
|
|
const llvm::markup::Document *getDocument() const { return Doc; }
|
|
|
|
CommentParts getParts() const {
|
|
return Parts;
|
|
}
|
|
|
|
Optional<const llvm::markup::Paragraph *>getBrief() const {
|
|
return Parts.Brief;
|
|
}
|
|
|
|
Optional<const llvm::markup::ReturnsField *>getReturnsField() const {
|
|
return Parts.ReturnsField;
|
|
}
|
|
|
|
ArrayRef<const llvm::markup::ParamField *> getParamFields() const {
|
|
return Parts.ParamFields;
|
|
}
|
|
|
|
ArrayRef<const llvm::markup::MarkupASTNode *> getBodyNodes() const {
|
|
return Parts.BodyNodes;
|
|
}
|
|
|
|
bool isEmpty() const {
|
|
return Parts.isEmpty();
|
|
}
|
|
|
|
// Only allow allocation using the allocator in MarkupContext or by
|
|
// placement new.
|
|
void *operator new(size_t Bytes, llvm::markup::MarkupContext &MC,
|
|
unsigned Alignment = alignof(DocComment));
|
|
void *operator new(size_t Bytes, void *Mem) {
|
|
assert(Mem);
|
|
return Mem;
|
|
}
|
|
|
|
// Make vanilla new/delete illegal.
|
|
void *operator new(size_t Bytes) = delete;
|
|
void operator delete(void *Data) = delete;
|
|
};
|
|
|
|
Optional<DocComment *>getDocComment(llvm::markup::MarkupContext &Context,
|
|
const Decl *D);
|
|
|
|
} // namespace swift
|
|
|
|
#endif // LLVM_SWIFT_AST_COMMENT_H
|
|
|