mirror of
https://github.com/apple/swift.git
synced 2025-12-21 12:14:44 +01:00
7a3a0a9e23
Adds a tool `swift-symbolgraph-extract` that reads an existing Swift module and prints a platform- and language-agnostic JSON description of the module, primarly for documentation. Adds a small sub-library `SymbolGraphGen` which houses the core implementation for collecting relevant information about declarations. The main entry point is integrated directly into the driver as a mode: the tool is meant to be run outside of the normal edit-compile-run/test workflow to avoid impacting build times. Along with common options for other tools, unique options include `pretty-print` for debugging, and a `minimum-access-level` options for including internal documentation. A symbol graph is a directed graph where the nodes are symbols in a module and the edges are relationships between them. For example, a `struct S` may have a member `var x`. The graph would have two nodes for `S` and `x`, and one "member-of" relationship edge. Other relationship kinds include "inherits-from" or "conforms to". The data format for a symbol graph is still under development and may change without notice until a specificiation and versioning scheme is published. Various aspects about a symbol are recorded in the nodes, such as availability, documentation comments, or data needed for printing the shapes of declarations without having to understand specifics about the langauge. Implicit and public-underscored stdlib declarations are not included by default. rdar://problem/55346798
124 lines
3.1 KiB
C++
124 lines
3.1 KiB
C++
//===--- DeclarationFragmentPrinter.h - Declaration Fragment Printer ------===//
|
|
//
|
|
// This source file is part of the Swift.org open source project
|
|
//
|
|
// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See https://swift.org/LICENSE.txt for license information
|
|
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef SWIFT_SYMBOLGRAPHGEN_DECLARATIONFRAGMENTPRINTER_H
|
|
#define SWIFT_SYMBOLGRAPHGEN_DECLARATIONFRAGMENTPRINTER_H
|
|
|
|
#include "llvm/Support/JSON.h"
|
|
#include "swift/AST/ASTPrinter.h"
|
|
#include "swift/Basic/LLVM.h"
|
|
|
|
namespace swift {
|
|
|
|
class Decl;
|
|
class Type;
|
|
class TypeDecl;
|
|
|
|
namespace symbolgraphgen {
|
|
|
|
struct SymbolGraphASTWalker;
|
|
|
|
/// Prints AST nodes as a stream of tagged fragments for syntax highlighting.
|
|
///
|
|
/// These fragments are meant to display a somewhat abbreviated part of the
|
|
/// declaration for display in documentation, ignoring things like member and
|
|
/// function bodies.
|
|
///
|
|
/// For example, a function:
|
|
///
|
|
/// ```swift
|
|
/// func foo() {
|
|
/// print("Hello, world!")
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// Will have fragments representing the `func foo()` part.
|
|
class DeclarationFragmentPrinter : public ASTPrinter {
|
|
enum class FragmentKind {
|
|
None,
|
|
Keyword,
|
|
Attribute,
|
|
NumberLiteral,
|
|
StringLiteral,
|
|
Identifier,
|
|
TypeIdentifier,
|
|
GenericParameter,
|
|
Text,
|
|
};
|
|
|
|
SymbolGraphASTWalker &Walker;
|
|
|
|
/// The output stream to print fragment objects to.
|
|
llvm::json::OStream &OS;
|
|
|
|
/// The current fragment being considered.
|
|
FragmentKind Kind;
|
|
|
|
/// The actual source text of the fragment.
|
|
SmallString<256> Spelling;
|
|
|
|
SmallString<256> USR;
|
|
|
|
StringRef getKindSpelling(FragmentKind Kind) const;
|
|
|
|
/// Open a new kind of fragment without committing its spelling.
|
|
void openFragment(FragmentKind Kind);
|
|
|
|
/// Close the current fragment if there is one, and commit it for display.
|
|
void closeFragment();
|
|
|
|
public:
|
|
DeclarationFragmentPrinter(SymbolGraphASTWalker &Walker,
|
|
llvm::json::OStream &OS,
|
|
Optional<StringRef> Key = None)
|
|
: Walker(Walker),
|
|
OS(OS),
|
|
Kind(FragmentKind::None) {
|
|
if (Key) {
|
|
OS.attributeBegin(*Key);
|
|
OS.arrayBegin();
|
|
} else {
|
|
OS.arrayBegin();
|
|
}
|
|
}
|
|
|
|
void printDeclLoc(const Decl *D) override;
|
|
|
|
void printDeclNameEndLoc(const Decl *D) override {
|
|
closeFragment();
|
|
}
|
|
|
|
void printNamePre(PrintNameContext Context) override;
|
|
|
|
void printStructurePre(PrintStructureKind Kind, const Decl *D) override;
|
|
|
|
void printNamePost(PrintNameContext Context) override {
|
|
closeFragment();
|
|
}
|
|
|
|
void printTypeRef(Type T, const TypeDecl *RefTo, Identifier Name,
|
|
PrintNameContext NameContext) override;
|
|
|
|
void printText(StringRef Text) override;
|
|
|
|
~DeclarationFragmentPrinter() {
|
|
closeFragment();
|
|
OS.arrayEnd();
|
|
OS.attributeEnd();
|
|
}
|
|
};
|
|
|
|
} // end namespace symbolgraphgen
|
|
} // end namespace swift
|
|
|
|
#endif // SWIFT_SYMBOLGRAPHGEN_DECLARATIONFRAGMENTPRINTER_H
|