LCOV - code coverage report
Current view: top level - clang/tools/extra/clang-doc - Representation.h (source / functions) Hit Total Coverage
Test: llvm-toolchain.info Lines: 41 41 100.0 %
Date: 2018-10-20 13:21:21 Functions: 12 13 92.3 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : ///===-- Representation.h - ClangDoc Representation -------------*- C++ -*-===//
       2             : //
       3             : //                     The LLVM Compiler Infrastructure
       4             : //
       5             : // This file is distributed under the University of Illinois Open Source
       6             : // License. See LICENSE.TXT for details.
       7             : //
       8             : //===----------------------------------------------------------------------===//
       9             : //
      10             : // This file defines the internal representations of different declaration
      11             : // types for the clang-doc tool.
      12             : //
      13             : //===----------------------------------------------------------------------===//
      14             : 
      15             : #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
      16             : #define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
      17             : 
      18             : #include "clang/AST/Type.h"
      19             : #include "clang/Basic/Specifiers.h"
      20             : #include "clang/Tooling/StandaloneExecution.h"
      21             : #include "llvm/ADT/Optional.h"
      22             : #include "llvm/ADT/SmallVector.h"
      23             : #include "llvm/ADT/StringExtras.h"
      24             : #include <array>
      25             : #include <string>
      26             : 
      27             : namespace clang {
      28             : namespace doc {
      29             : 
      30             : // SHA1'd hash of a USR.
      31             : using SymbolID = std::array<uint8_t, 20>;
      32             : 
      33             : struct Info;
      34             : struct FunctionInfo;
      35             : struct EnumInfo;
      36             : 
      37             : enum class InfoType {
      38             :   IT_default,
      39             :   IT_namespace,
      40             :   IT_record,
      41             :   IT_function,
      42             :   IT_enum
      43             : };
      44             : 
      45             : // A representation of a parsed comment.
      46             : struct CommentInfo {
      47           3 :   CommentInfo() = default;
      48             :   CommentInfo(CommentInfo &Other) = delete;
      49           6 :   CommentInfo(CommentInfo &&Other) = default;
      50             : 
      51             :   SmallString<16>
      52             :       Kind; // Kind of comment (FullComment, ParagraphComment, TextComment,
      53             :             // InlineCommandComment, HTMLStartTagComment, HTMLEndTagComment,
      54             :             // BlockCommandComment, ParamCommandComment,
      55             :             // TParamCommandComment, VerbatimBlockComment,
      56             :             // VerbatimBlockLineComment, VerbatimLineComment).
      57             :   SmallString<64> Text;      // Text of the comment.
      58             :   SmallString<16> Name;      // Name of the comment (for Verbatim and HTML).
      59             :   SmallString<8> Direction;  // Parameter direction (for (T)ParamCommand).
      60             :   SmallString<16> ParamName; // Parameter name (for (T)ParamCommand).
      61             :   SmallString<16> CloseName; // Closing tag name (for VerbatimBlock).
      62             :   bool SelfClosing = false;  // Indicates if tag is self-closing (for HTML).
      63             :   bool Explicit = false; // Indicates if the direction of a param is explicit
      64             :                          // (for (T)ParamCommand).
      65             :   llvm::SmallVector<SmallString<16>, 4>
      66             :       AttrKeys; // List of attribute keys (for HTML).
      67             :   llvm::SmallVector<SmallString<16>, 4>
      68             :       AttrValues; // List of attribute values for each key (for HTML).
      69             :   llvm::SmallVector<SmallString<16>, 4>
      70             :       Args; // List of arguments to commands (for InlineCommand).
      71             :   std::vector<std::unique_ptr<CommentInfo>>
      72             :       Children; // List of child comments for this CommentInfo.
      73             : };
      74             : 
      75         192 : struct Reference {
      76          93 :   Reference() = default;
      77          20 :   Reference(llvm::StringRef Name) : Name(Name) {}
      78             :   Reference(SymbolID USR, StringRef Name, InfoType IT)
      79          50 :       : USR(USR), Name(Name), RefType(IT) {}
      80             : 
      81             :   bool operator==(const Reference &Other) const {
      82          19 :     return std::tie(USR, Name, RefType) ==
      83          38 :            std::tie(Other.USR, Other.Name, Other.RefType);
      84             :   }
      85             : 
      86             :   SymbolID USR = SymbolID(); // Unique identifer for referenced decl
      87             :   SmallString<16> Name;      // Name of type (possibly unresolved).
      88             :   InfoType RefType = InfoType::IT_default; // Indicates the type of this
      89             :                                            // Reference (namespace, record,
      90             :                                            // function, enum, default).
      91             : };
      92             : 
      93             : // A base struct for TypeInfos
      94             : struct TypeInfo {
      95             :   TypeInfo() = default;
      96          16 :   TypeInfo(SymbolID Type, StringRef Field, InfoType IT)
      97          16 :       : Type(Type, Field, IT) {}
      98          20 :   TypeInfo(llvm::StringRef RefName) : Type(RefName) {}
      99             : 
     100             :   bool operator==(const TypeInfo &Other) const { return Type == Other.Type; }
     101             : 
     102             :   Reference Type; // Referenced type in this info.
     103             : };
     104             : 
     105             : // Info for field types.
     106             : struct FieldTypeInfo : public TypeInfo {
     107             :   FieldTypeInfo() = default;
     108             :   FieldTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
     109             :                 llvm::StringRef Name)
     110             :       : TypeInfo(Type, Field, IT), Name(Name) {}
     111          20 :   FieldTypeInfo(llvm::StringRef RefName, llvm::StringRef Name)
     112          20 :       : TypeInfo(RefName), Name(Name) {}
     113             : 
     114             :   bool operator==(const FieldTypeInfo &Other) const {
     115          14 :     return std::tie(Type, Name) == std::tie(Other.Type, Other.Name);
     116             :   }
     117             : 
     118             :   SmallString<16> Name; // Name associated with this info.
     119             : };
     120             : 
     121             : // Info for member types.
     122          12 : struct MemberTypeInfo : public FieldTypeInfo {
     123             :   MemberTypeInfo() = default;
     124             :   MemberTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
     125             :                  llvm::StringRef Name, AccessSpecifier Access)
     126             :       : FieldTypeInfo(Type, Field, IT, Name), Access(Access) {}
     127             :   MemberTypeInfo(llvm::StringRef RefName, llvm::StringRef Name,
     128             :                  AccessSpecifier Access)
     129           6 :       : FieldTypeInfo(RefName, Name), Access(Access) {}
     130             : 
     131             :   bool operator==(const MemberTypeInfo &Other) const {
     132           3 :     return std::tie(Type, Name, Access) ==
     133           3 :            std::tie(Other.Type, Other.Name, Other.Access);
     134             :   }
     135             : 
     136             :   AccessSpecifier Access = AccessSpecifier::AS_none; // Access level associated
     137             :                                                      // with this info (public,
     138             :                                                      // protected, private,
     139             :                                                      // none).
     140             : };
     141             : 
     142         106 : struct Location {
     143             :   Location() = default;
     144             :   Location(int LineNumber, SmallString<16> Filename)
     145          56 :       : LineNumber(LineNumber), Filename(std::move(Filename)) {}
     146             : 
     147             :   bool operator==(const Location &Other) const {
     148          13 :     return std::tie(LineNumber, Filename) ==
     149          26 :            std::tie(Other.LineNumber, Other.Filename);
     150             :   }
     151             : 
     152             :   int LineNumber;           // Line number of this Location.
     153             :   SmallString<32> Filename; // File for this Location.
     154             : };
     155             : 
     156             : /// A base struct for Infos.
     157             : struct Info {
     158             :   Info() = default;
     159          77 :   Info(InfoType IT) : IT(IT) {}
     160          10 :   Info(InfoType IT, SymbolID USR) : USR(USR), IT(IT) {}
     161             :   Info(InfoType IT, SymbolID USR, StringRef Name)
     162          10 :       : USR(USR), IT(IT), Name(Name) {}
     163             :   Info(const Info &Other) = delete;
     164          46 :   Info(Info &&Other) = default;
     165             : 
     166         174 :   virtual ~Info() = default;
     167             : 
     168             :   SymbolID USR =
     169             :       SymbolID(); // Unique identifier for the decl described by this Info.
     170             :   const InfoType IT = InfoType::IT_default; // InfoType of this particular Info.
     171             :   SmallString<16> Name;                     // Unqualified name of the decl.
     172             :   llvm::SmallVector<Reference, 4>
     173             :       Namespace; // List of parent namespaces for this decl.
     174             :   std::vector<CommentInfo> Description; // Comment description of this decl.
     175             : 
     176             :   void mergeBase(Info &&I);
     177             :   bool mergeable(const Info &Other);
     178             : 
     179             :   // Returns a reference to the parent scope (that is, the immediate parent
     180             :   // namespace or class in which this decl resides).
     181             :   llvm::Expected<Reference> getEnclosingScope();
     182             : };
     183             : 
     184             : // Info for namespaces.
     185             : struct NamespaceInfo : public Info {
     186          10 :   NamespaceInfo() : Info(InfoType::IT_namespace) {}
     187          24 :   NamespaceInfo(SymbolID USR) : Info(InfoType::IT_namespace, USR) {}
     188           2 :   NamespaceInfo(SymbolID USR, StringRef Name)
     189           2 :       : Info(InfoType::IT_namespace, USR, Name) {}
     190             : 
     191             :   void merge(NamespaceInfo &&I);
     192             : 
     193             :   // Namespaces and Records are references because they will be properly
     194             :   // documented in their own info, while the entirety of Functions and Enums are
     195             :   // included here because they should not have separate documentation from
     196             :   // their scope.
     197             :   std::vector<Reference> ChildNamespaces;
     198             :   std::vector<Reference> ChildRecords;
     199             :   std::vector<FunctionInfo> ChildFunctions;
     200             :   std::vector<EnumInfo> ChildEnums;
     201             : };
     202             : 
     203             : // Info for symbols.
     204             : struct SymbolInfo : public Info {
     205          60 :   SymbolInfo(InfoType IT) : Info(IT) {}
     206           4 :   SymbolInfo(InfoType IT, SymbolID USR) : Info(IT, USR) {}
     207           8 :   SymbolInfo(InfoType IT, SymbolID USR, StringRef Name) : Info(IT, USR, Name) {}
     208             : 
     209             :   void merge(SymbolInfo &&I);
     210             : 
     211             :   llvm::Optional<Location> DefLoc;    // Location where this decl is defined.
     212             :   llvm::SmallVector<Location, 2> Loc; // Locations where this decl is declared.
     213             : };
     214             : 
     215             : // TODO: Expand to allow for documenting templating and default args.
     216             : // Info for functions.
     217             : struct FunctionInfo : public SymbolInfo {
     218          93 :   FunctionInfo() : SymbolInfo(InfoType::IT_function) {}
     219             :   FunctionInfo(SymbolID USR) : SymbolInfo(InfoType::IT_function, USR) {}
     220             : 
     221             :   void merge(FunctionInfo &&I);
     222             : 
     223             :   bool IsMethod = false; // Indicates whether this function is a class method.
     224             :   Reference Parent;      // Reference to the parent class decl for this method.
     225             :   TypeInfo ReturnType;   // Info about the return type of this function.
     226             :   llvm::SmallVector<FieldTypeInfo, 4> Params; // List of parameters.
     227             :   // Access level for this method (public, private, protected, none).
     228             :   AccessSpecifier Access = AccessSpecifier::AS_none;
     229             : };
     230             : 
     231             : // TODO: Expand to allow for documenting templating, inheritance access,
     232             : // friend classes
     233             : // Info for types.
     234             : struct RecordInfo : public SymbolInfo {
     235          18 :   RecordInfo() : SymbolInfo(InfoType::IT_record) {}
     236           6 :   RecordInfo(SymbolID USR) : SymbolInfo(InfoType::IT_record, USR) {}
     237           8 :   RecordInfo(SymbolID USR, StringRef Name)
     238           8 :       : SymbolInfo(InfoType::IT_record, USR, Name) {}
     239             : 
     240             :   void merge(RecordInfo &&I);
     241             : 
     242             :   TagTypeKind TagType = TagTypeKind::TTK_Struct; // Type of this record
     243             :                                                  // (struct, class, union,
     244             :                                                  // interface).
     245             :   llvm::SmallVector<MemberTypeInfo, 4>
     246             :       Members;                             // List of info about record members.
     247             :   llvm::SmallVector<Reference, 4> Parents; // List of base/parent records
     248             :                                            // (does not include virtual
     249             :                                            // parents).
     250             :   llvm::SmallVector<Reference, 4>
     251             :       VirtualParents; // List of virtual base/parent records.
     252             : 
     253             :   // Records are references because they will be properly
     254             :   // documented in their own info, while the entirety of Functions and Enums are
     255             :   // included here because they should not have separate documentation from
     256             :   // their scope.
     257             :   std::vector<Reference> ChildRecords;
     258             :   std::vector<FunctionInfo> ChildFunctions;
     259             :   std::vector<EnumInfo> ChildEnums;
     260             : };
     261             : 
     262             : // TODO: Expand to allow for documenting templating.
     263             : // Info for types.
     264           5 : struct EnumInfo : public SymbolInfo {
     265          42 :   EnumInfo() : SymbolInfo(InfoType::IT_enum) {}
     266             :   EnumInfo(SymbolID USR) : SymbolInfo(InfoType::IT_enum, USR) {}
     267             : 
     268             :   void merge(EnumInfo &&I);
     269             : 
     270             :   bool Scoped =
     271             :       false; // Indicates whether this enum is scoped (e.g. enum class).
     272             :   llvm::SmallVector<SmallString<16>, 4> Members; // List of enum members.
     273             : };
     274             : 
     275             : // TODO: Add functionality to include separate markdown pages.
     276             : 
     277             : // A standalone function to call to merge a vector of infos into one.
     278             : // This assumes that all infos in the vector are of the same type, and will fail
     279             : // if they are different.
     280             : llvm::Expected<std::unique_ptr<Info>>
     281             : mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
     282             : 
     283             : struct ClangDocContext {
     284             :   tooling::ExecutionContext *ECtx;
     285             :   bool PublicOnly;
     286             : };
     287             : 
     288             : } // namespace doc
     289             : } // namespace clang
     290             : 
     291             : #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H

Generated by: LCOV version 1.13