Serialize.cpp | Explore in Territory

//===-- Serialize.cpp - ClangDoc Serializer ---------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#include "Serialize.h"
#include "BitcodeWriter.h"
#include "clang/AST/Comment.h"
#include "clang/Index/USRGeneration.h"
#include "clang/Lex/Lexer.h"
#include "llvm/ADT/Hashing.h"
#include "llvm/ADT/StringExtras.h"
#include "llvm/Support/SHA1.h"

FullComment;

namespace clang {
namespace doc {
namespace serialize {

SymbolID hashUSR(llvm::StringRef USR) { … }

template <typename T>
static void
populateParentNamespaces(llvm::SmallVector<Reference, 4> &Namespaces,
                         const T *D, bool &IsAnonymousNamespace);

static void populateMemberTypeInfo(MemberTypeInfo &I, const FieldDecl *D);

// A function to extract the appropriate relative path for a given info's
// documentation. The path returned is a composite of the parent namespaces.
//
// Example: Given the below, the directory path for class C info will be
// <root>/A/B
//
// namespace A {
// namespace B {
//
// class C {};
//
// }
// }
llvm::SmallString<128>
getInfoRelativePath(const llvm::SmallVectorImpl<doc::Reference> &Namespaces) { … }

llvm::SmallString<128> getInfoRelativePath(const Decl *D) { … }

class ClangDocCommentVisitor
    : public ConstCommentVisitor<ClangDocCommentVisitor> { … };

void ClangDocCommentVisitor::parseComment(const comments::Comment *C) { … }

void ClangDocCommentVisitor::visitTextComment(const TextComment *C) { … }

void ClangDocCommentVisitor::visitInlineCommandComment(
    const InlineCommandComment *C) { … }

void ClangDocCommentVisitor::visitHTMLStartTagComment(
    const HTMLStartTagComment *C) { … }

void ClangDocCommentVisitor::visitHTMLEndTagComment(
    const HTMLEndTagComment *C) { … }

void ClangDocCommentVisitor::visitBlockCommandComment(
    const BlockCommandComment *C) { … }

void ClangDocCommentVisitor::visitParamCommandComment(
    const ParamCommandComment *C) { … }

void ClangDocCommentVisitor::visitTParamCommandComment(
    const TParamCommandComment *C) { … }

void ClangDocCommentVisitor::visitVerbatimBlockComment(
    const VerbatimBlockComment *C) { … }

void ClangDocCommentVisitor::visitVerbatimBlockLineComment(
    const VerbatimBlockLineComment *C) { … }

void ClangDocCommentVisitor::visitVerbatimLineComment(
    const VerbatimLineComment *C) { … }

bool ClangDocCommentVisitor::isWhitespaceOnly(llvm::StringRef S) const { … }

std::string ClangDocCommentVisitor::getCommandName(unsigned CommandID) const { … }

// Serializing functions.

std::string getSourceCode(const Decl *D, const SourceRange &R) { … }

template <typename T> static std::string serialize(T &I) { … }

std::string serialize(std::unique_ptr<Info> &I) { … }

static void parseFullComment(const FullComment *C, CommentInfo &CI) { … }

static SymbolID getUSRForDecl(const Decl *D) { … }

static TagDecl *getTagDeclForType(const QualType &T) { … }

static RecordDecl *getRecordDeclForType(const QualType &T) { … }

TypeInfo getTypeInfoForType(const QualType &T) { … }

static bool isPublic(const clang::AccessSpecifier AS,
                     const clang::Linkage Link) { … }

static bool shouldSerializeInfo(bool PublicOnly, bool IsInAnonymousNamespace,
                                const NamedDecl *D) { … }

// The InsertChild functions insert the given info into the given scope using
// the method appropriate for that type. Some types are moved into the
// appropriate vector, while other types have Reference objects generated to
// refer to them.
//
// See MakeAndInsertIntoParent().
static void InsertChild(ScopeChildren &Scope, const NamespaceInfo &Info) { … }

static void InsertChild(ScopeChildren &Scope, const RecordInfo &Info) { … }

static void InsertChild(ScopeChildren &Scope, EnumInfo Info) { … }

static void InsertChild(ScopeChildren &Scope, FunctionInfo Info) { … }

static void InsertChild(ScopeChildren &Scope, TypedefInfo Info) { … }

// Creates a parent of the correct type for the given child and inserts it into
// that parent.
//
// This is complicated by the fact that namespaces and records are inserted by
// reference (constructing a "Reference" object with that namespace/record's
// info), while everything else is inserted by moving it directly into the child
// vectors.
//
// For namespaces and records, explicitly specify a const& template parameter
// when invoking this function:
//   MakeAndInsertIntoParent<const Record&>(...);
// Otherwise, specify an rvalue reference <EnumInfo&&> and move into the
// parameter. Since each variant is used once, it's not worth having a more
// elaborate system to automatically deduce this information.
template <typename ChildType>
std::unique_ptr<Info> MakeAndInsertIntoParent(ChildType Child) { … }

// There are two uses for this function.
// 1) Getting the resulting mode of inheritance of a record.
//    Example: class A {}; class B : private A {}; class C : public B {};
//    It's explicit that C is publicly inherited from C and B is privately
//    inherited from A. It's not explicit but C is also privately inherited from
//    A. This is the AS that this function calculates. FirstAS is the
//    inheritance mode of `class C : B` and SecondAS is the inheritance mode of
//    `class B : A`.
// 2) Getting the inheritance mode of an inherited attribute / method.
//    Example : class A { public: int M; }; class B : private A {};
//    Class B is inherited from class A, which has a public attribute. This
//    attribute is now part of the derived class B but it's not public. This
//    will be private because the inheritance is private. This is the AS that
//    this function calculates. FirstAS is the inheritance mode and SecondAS is
//    the AS of the attribute / method.
static AccessSpecifier getFinalAccessSpecifier(AccessSpecifier FirstAS,
                                               AccessSpecifier SecondAS) { … }

// The Access parameter is only provided when parsing the field of an inherited
// record, the access specification of the field depends on the inheritance mode
static void parseFields(RecordInfo &I, const RecordDecl *D, bool PublicOnly,
                        AccessSpecifier Access = AccessSpecifier::AS_public) { … }

static void parseEnumerators(EnumInfo &I, const EnumDecl *D) { … }

static void parseParameters(FunctionInfo &I, const FunctionDecl *D) { … }

// TODO: Remove the serialization of Parents and VirtualParents, this
// information is also extracted in the other definition of parseBases.
static void parseBases(RecordInfo &I, const CXXRecordDecl *D) { … }

template <typename T>
static void
populateParentNamespaces(llvm::SmallVector<Reference, 4> &Namespaces,
                         const T *D, bool &IsInAnonymousNamespace) { … }

void PopulateTemplateParameters(std::optional<TemplateInfo> &TemplateInfo,
                                const clang::Decl *D) { … }

TemplateParamInfo TemplateArgumentToInfo(const clang::Decl *D,
                                         const TemplateArgument &Arg) { … }

template <typename T>
static void populateInfo(Info &I, const T *D, const FullComment *C,
                         bool &IsInAnonymousNamespace) { … }

template <typename T>
static void populateSymbolInfo(SymbolInfo &I, const T *D, const FullComment *C,
                               int LineNumber, StringRef Filename,
                               bool IsFileInRootDir,
                               bool &IsInAnonymousNamespace) { … }

static void populateFunctionInfo(FunctionInfo &I, const FunctionDecl *D,
                                 const FullComment *FC, int LineNumber,
                                 StringRef Filename, bool IsFileInRootDir,
                                 bool &IsInAnonymousNamespace) { … }

static void populateMemberTypeInfo(MemberTypeInfo &I, const FieldDecl *D) { … }

static void
parseBases(RecordInfo &I, const CXXRecordDecl *D, bool IsFileInRootDir,
           bool PublicOnly, bool IsParent,
           AccessSpecifier ParentAccess = AccessSpecifier::AS_public) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const NamespaceDecl *D, const FullComment *FC, int LineNumber,
         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const RecordDecl *D, const FullComment *FC, int LineNumber,
         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const FunctionDecl *D, const FullComment *FC, int LineNumber,
         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const CXXMethodDecl *D, const FullComment *FC, int LineNumber,
         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const TypedefDecl *D, const FullComment *FC, int LineNumber,
         StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

// A type alias is a C++ "using" declaration for a type. It gets mapped to a
// TypedefInfo with the IsUsing flag set.
std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const TypeAliasDecl *D, const FullComment *FC, int LineNumber,
         StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
emitInfo(const EnumDecl *D, const FullComment *FC, int LineNumber,
         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) { … }

} // namespace serialize
} // namespace doc
} // namespace clang
llvm/clang-tools-extra/clang-doc/Serialize.cpp
