clang-tools-extra/clang-doc/Representation.cpp

   1 ///===-- Representation.cpp - ClangDoc Representation -----------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file defines the merging of different types of infos. The data in the
  10 // calling Info is preserved during a merge unless that field is empty or
  11 // default. In that case, the data from the parameter Info is used to replace
  12 // the empty or default data.
  13 //
  14 // For most fields, the first decl seen provides the data. Exceptions to this
  15 // include the location and description fields, which are collections of data on
  16 // all decls related to a given definition. All other fields are ignored in new
  17 // decls unless the first seen decl didn't, for whatever reason, incorporate
  18 // data on that field (e.g. a forward declared class wouldn't have information
  19 // on members on the forward declaration, but would have the class name).
  20 //
  21 //===----------------------------------------------------------------------===//
  22 #include "Representation.h"
  23 #include "llvm/Support/Error.h"
  24 #include "llvm/Support/Path.h"
  25
  26 namespace clang {
  27 namespace doc {
  28
  29 namespace {
  30
  31 const SymbolID EmptySID = SymbolID();
  32
  33 template <typename T>
  34 llvm::Expected<std::unique_ptr<Info>>
  35 reduce(std::vector<std::unique_ptr<Info>> &Values) {
  36   if (Values.empty() || !Values[0])
  37     return llvm::createStringError(llvm::inconvertibleErrorCode(),
  38                                    "no value to reduce");
  39   std::unique_ptr<Info> Merged = std::make_unique<T>(Values[0]->USR);
  40   T *Tmp = static_cast<T *>(Merged.get());
  41   for (auto &I : Values)
  42     Tmp->merge(std::move(*static_cast<T *>(I.get())));
  43   return std::move(Merged);
  44 }
  45
  46 // Return the index of the matching child in the vector, or -1 if merge is not
  47 // necessary.
  48 template <typename T>
  49 int getChildIndexIfExists(std::vector<T> &Children, T &ChildToMerge) {
  50   for (unsigned long I = 0; I < Children.size(); I++) {
  51     if (ChildToMerge.USR == Children[I].USR)
  52       return I;
  53   }
  54   return -1;
  55 }
  56
  57 template <typename T>
  58 void reduceChildren(std::vector<T> &Children,
  59                     std::vector<T> &&ChildrenToMerge) {
  60   for (auto &ChildToMerge : ChildrenToMerge) {
  61     int MergeIdx = getChildIndexIfExists(Children, ChildToMerge);
  62     if (MergeIdx == -1) {
  63       Children.push_back(std::move(ChildToMerge));
  64       continue;
  65     }
  66     Children[MergeIdx].merge(std::move(ChildToMerge));
  67   }
  68 }
  69
  70 } // namespace
  71
  72 // Dispatch function.
  73 llvm::Expected<std::unique_ptr<Info>>
  74 mergeInfos(std::vector<std::unique_ptr<Info>> &Values) {
  75   if (Values.empty() || !Values[0])
  76     return llvm::createStringError(llvm::inconvertibleErrorCode(),
  77                                    "no info values to merge");
  78
  79   switch (Values[0]->IT) {
  80   case InfoType::IT_namespace:
  81     return reduce<NamespaceInfo>(Values);
  82   case InfoType::IT_record:
  83     return reduce<RecordInfo>(Values);
  84   case InfoType::IT_enum:
  85     return reduce<EnumInfo>(Values);
  86   case InfoType::IT_function:
  87     return reduce<FunctionInfo>(Values);
  88   case InfoType::IT_typedef:
  89     return reduce<TypedefInfo>(Values);
  90   default:
  91     return llvm::createStringError(llvm::inconvertibleErrorCode(),
  92                                    "unexpected info type");
  93   }
  94 }
  95
  96 bool CommentInfo::operator==(const CommentInfo &Other) const {
  97   auto FirstCI = std::tie(Kind, Text, Name, Direction, ParamName, CloseName,
  98                           SelfClosing, Explicit, AttrKeys, AttrValues, Args);
  99   auto SecondCI =
 100       std::tie(Other.Kind, Other.Text, Other.Name, Other.Direction,
 101                Other.ParamName, Other.CloseName, Other.SelfClosing,
 102                Other.Explicit, Other.AttrKeys, Other.AttrValues, Other.Args);
 103
 104   if (FirstCI != SecondCI || Children.size() != Other.Children.size())
 105     return false;
 106
 107   return std::equal(Children.begin(), Children.end(), Other.Children.begin(),
 108                     llvm::deref<std::equal_to<>>{});
 109 }
 110
 111 bool CommentInfo::operator<(const CommentInfo &Other) const {
 112   auto FirstCI = std::tie(Kind, Text, Name, Direction, ParamName, CloseName,
 113                           SelfClosing, Explicit, AttrKeys, AttrValues, Args);
 114   auto SecondCI =
 115       std::tie(Other.Kind, Other.Text, Other.Name, Other.Direction,
 116                Other.ParamName, Other.CloseName, Other.SelfClosing,
 117                Other.Explicit, Other.AttrKeys, Other.AttrValues, Other.Args);
 118
 119   if (FirstCI < SecondCI)
 120     return true;
 121
 122   if (FirstCI == SecondCI) {
 123     return std::lexicographical_compare(
 124         Children.begin(), Children.end(), Other.Children.begin(),
 125         Other.Children.end(), llvm::deref<std::less<>>());
 126   }
 127
 128   return false;
 129 }
 130
 131 static llvm::SmallString<64>
 132 calculateRelativeFilePath(const InfoType &Type, const StringRef &Path,
 133                           const StringRef &Name, const StringRef &CurrentPath) {
 134   llvm::SmallString<64> FilePath;
 135
 136   if (CurrentPath != Path) {
 137     // iterate back to the top
 138     for (llvm::sys::path::const_iterator I =
 139              llvm::sys::path::begin(CurrentPath);
 140          I != llvm::sys::path::end(CurrentPath); ++I)
 141       llvm::sys::path::append(FilePath, "..");
 142     llvm::sys::path::append(FilePath, Path);
 143   }
 144
 145   // Namespace references have a Path to the parent namespace, but
 146   // the file is actually in the subdirectory for the namespace.
 147   if (Type == doc::InfoType::IT_namespace)
 148     llvm::sys::path::append(FilePath, Name);
 149
 150   return llvm::sys::path::relative_path(FilePath);
 151 }
 152
 153 llvm::SmallString<64>
 154 Reference::getRelativeFilePath(const StringRef &CurrentPath) const {
 155   return calculateRelativeFilePath(RefType, Path, Name, CurrentPath);
 156 }
 157
 158 llvm::SmallString<16> Reference::getFileBaseName() const {
 159   if (RefType == InfoType::IT_namespace)
 160     return llvm::SmallString<16>("index");
 161
 162   return Name;
 163 }
 164
 165 llvm::SmallString<64>
 166 Info::getRelativeFilePath(const StringRef &CurrentPath) const {
 167   return calculateRelativeFilePath(IT, Path, extractName(), CurrentPath);
 168 }
 169
 170 llvm::SmallString<16> Info::getFileBaseName() const {
 171   if (IT == InfoType::IT_namespace)
 172     return llvm::SmallString<16>("index");
 173
 174   return extractName();
 175 }
 176
 177 bool Reference::mergeable(const Reference &Other) {
 178   return RefType == Other.RefType && USR == Other.USR;
 179 }
 180
 181 void Reference::merge(Reference &&Other) {
 182   assert(mergeable(Other));
 183   if (Name.empty())
 184     Name = Other.Name;
 185   if (Path.empty())
 186     Path = Other.Path;
 187 }
 188
 189 void Info::mergeBase(Info &&Other) {
 190   assert(mergeable(Other));
 191   if (USR == EmptySID)
 192     USR = Other.USR;
 193   if (Name == "")
 194     Name = Other.Name;
 195   if (Path == "")
 196     Path = Other.Path;
 197   if (Namespace.empty())
 198     Namespace = std::move(Other.Namespace);
 199   // Unconditionally extend the description, since each decl may have a comment.
 200   std::move(Other.Description.begin(), Other.Description.end(),
 201             std::back_inserter(Description));
 202   llvm::sort(Description);
 203   auto Last = std::unique(Description.begin(), Description.end());
 204   Description.erase(Last, Description.end());
 205 }
 206
 207 bool Info::mergeable(const Info &Other) {
 208   return IT == Other.IT && USR == Other.USR;
 209 }
 210
 211 void SymbolInfo::merge(SymbolInfo &&Other) {
 212   assert(mergeable(Other));
 213   if (!DefLoc)
 214     DefLoc = std::move(Other.DefLoc);
 215   // Unconditionally extend the list of locations, since we want all of them.
 216   std::move(Other.Loc.begin(), Other.Loc.end(), std::back_inserter(Loc));
 217   llvm::sort(Loc);
 218   auto Last = std::unique(Loc.begin(), Loc.end());
 219   Loc.erase(Last, Loc.end());
 220   mergeBase(std::move(Other));
 221 }
 222
 223 NamespaceInfo::NamespaceInfo(SymbolID USR, StringRef Name, StringRef Path)
 224       : Info(InfoType::IT_namespace, USR, Name, Path) {}
 225
 226 void NamespaceInfo::merge(NamespaceInfo &&Other) {
 227   assert(mergeable(Other));
 228   // Reduce children if necessary.
 229   reduceChildren(Children.Namespaces, std::move(Other.Children.Namespaces));
 230   reduceChildren(Children.Records, std::move(Other.Children.Records));
 231   reduceChildren(Children.Functions, std::move(Other.Children.Functions));
 232   reduceChildren(Children.Enums, std::move(Other.Children.Enums));
 233   reduceChildren(Children.Typedefs, std::move(Other.Children.Typedefs));
 234   mergeBase(std::move(Other));
 235 }
 236
 237 RecordInfo::RecordInfo(SymbolID USR, StringRef Name, StringRef Path)
 238     : SymbolInfo(InfoType::IT_record, USR, Name, Path) {}
 239
 240 void RecordInfo::merge(RecordInfo &&Other) {
 241   assert(mergeable(Other));
 242   if (!llvm::to_underlying(TagType))
 243     TagType = Other.TagType;
 244   IsTypeDef = IsTypeDef || Other.IsTypeDef;
 245   if (Members.empty())
 246     Members = std::move(Other.Members);
 247   if (Bases.empty())
 248     Bases = std::move(Other.Bases);
 249   if (Parents.empty())
 250     Parents = std::move(Other.Parents);
 251   if (VirtualParents.empty())
 252     VirtualParents = std::move(Other.VirtualParents);
 253   // Reduce children if necessary.
 254   reduceChildren(Children.Records, std::move(Other.Children.Records));
 255   reduceChildren(Children.Functions, std::move(Other.Children.Functions));
 256   reduceChildren(Children.Enums, std::move(Other.Children.Enums));
 257   reduceChildren(Children.Typedefs, std::move(Other.Children.Typedefs));
 258   SymbolInfo::merge(std::move(Other));
 259   if (!Template)
 260     Template = Other.Template;
 261 }
 262
 263 void EnumInfo::merge(EnumInfo &&Other) {
 264   assert(mergeable(Other));
 265   if (!Scoped)
 266     Scoped = Other.Scoped;
 267   if (Members.empty())
 268     Members = std::move(Other.Members);
 269   SymbolInfo::merge(std::move(Other));
 270 }
 271
 272 void FunctionInfo::merge(FunctionInfo &&Other) {
 273   assert(mergeable(Other));
 274   if (!IsMethod)
 275     IsMethod = Other.IsMethod;
 276   if (!Access)
 277     Access = Other.Access;
 278   if (ReturnType.Type.USR == EmptySID && ReturnType.Type.Name == "")
 279     ReturnType = std::move(Other.ReturnType);
 280   if (Parent.USR == EmptySID && Parent.Name == "")
 281     Parent = std::move(Other.Parent);
 282   if (Params.empty())
 283     Params = std::move(Other.Params);
 284   SymbolInfo::merge(std::move(Other));
 285   if (!Template)
 286     Template = Other.Template;
 287 }
 288
 289 void TypedefInfo::merge(TypedefInfo &&Other) {
 290   assert(mergeable(Other));
 291   if (!IsUsing)
 292     IsUsing = Other.IsUsing;
 293   if (Underlying.Type.Name == "")
 294     Underlying = Other.Underlying;
 295   SymbolInfo::merge(std::move(Other));
 296 }
 297
 298 BaseRecordInfo::BaseRecordInfo() : RecordInfo() {}
 299
 300 BaseRecordInfo::BaseRecordInfo(SymbolID USR, StringRef Name, StringRef Path,
 301                                bool IsVirtual, AccessSpecifier Access,
 302                                bool IsParent)
 303     : RecordInfo(USR, Name, Path), IsVirtual(IsVirtual), Access(Access),
 304       IsParent(IsParent) {}
 305
 306 llvm::SmallString<16> Info::extractName() const {
 307   if (!Name.empty())
 308     return Name;
 309
 310   switch (IT) {
 311   case InfoType::IT_namespace:
 312     // Cover the case where the project contains a base namespace called
 313     // 'GlobalNamespace' (i.e. a namespace at the same level as the global
 314     // namespace, which would conflict with the hard-coded global namespace name
 315     // below.)
 316     if (Name == "GlobalNamespace" && Namespace.empty())
 317       return llvm::SmallString<16>("@GlobalNamespace");
 318     // The case of anonymous namespaces is taken care of in serialization,
 319     // so here we can safely assume an unnamed namespace is the global
 320     // one.
 321     return llvm::SmallString<16>("GlobalNamespace");
 322   case InfoType::IT_record:
 323     return llvm::SmallString<16>("@nonymous_record_" +
 324                                  toHex(llvm::toStringRef(USR)));
 325   case InfoType::IT_enum:
 326     return llvm::SmallString<16>("@nonymous_enum_" +
 327                                  toHex(llvm::toStringRef(USR)));
 328   case InfoType::IT_typedef:
 329     return llvm::SmallString<16>("@nonymous_typedef_" +
 330                                  toHex(llvm::toStringRef(USR)));
 331   case InfoType::IT_function:
 332     return llvm::SmallString<16>("@nonymous_function_" +
 333                                  toHex(llvm::toStringRef(USR)));
 334   case InfoType::IT_default:
 335     return llvm::SmallString<16>("@nonymous_" + toHex(llvm::toStringRef(USR)));
 336   }
 337   llvm_unreachable("Invalid InfoType.");
 338   return llvm::SmallString<16>("");
 339 }
 340
 341 // Order is based on the Name attribute: case insensitive order
 342 bool Index::operator<(const Index &Other) const {
 343   // Loop through each character of both strings
 344   for (unsigned I = 0; I < Name.size() && I < Other.Name.size(); ++I) {
 345     // Compare them after converting both to lower case
 346     int D = tolower(Name[I]) - tolower(Other.Name[I]);
 347     if (D == 0)
 348       continue;
 349     return D < 0;
 350   }
 351   // If both strings have the size it means they would be equal if changed to
 352   // lower case. In here, lower case will be smaller than upper case
 353   // Example: string < stRing = true
 354   // This is the opposite of how operator < handles strings
 355   if (Name.size() == Other.Name.size())
 356     return Name > Other.Name;
 357   // If they are not the same size; the shorter string is smaller
 358   return Name.size() < Other.Name.size();
 359 }
 360
 361 void Index::sort() {
 362   llvm::sort(Children);
 363   for (auto &C : Children)
 364     C.sort();
 365 }
 366
 367 ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
 368                                  StringRef ProjectName, bool PublicOnly,
 369                                  StringRef OutDirectory, StringRef SourceRoot,
 370                                  StringRef RepositoryUrl,
 371                                  std::vector<std::string> UserStylesheets)
 372     : ECtx(ECtx), ProjectName(ProjectName), PublicOnly(PublicOnly),
 373       OutDirectory(OutDirectory), UserStylesheets(UserStylesheets) {
 374   llvm::SmallString<128> SourceRootDir(SourceRoot);
 375   if (SourceRoot.empty())
 376     // If no SourceRoot was provided the current path is used as the default
 377     llvm::sys::fs::current_path(SourceRootDir);
 378   this->SourceRoot = std::string(SourceRootDir);
 379   if (!RepositoryUrl.empty()) {
 380     this->RepositoryUrl = std::string(RepositoryUrl);
 381     if (!RepositoryUrl.empty() && !RepositoryUrl.starts_with("http://") &&
 382         !RepositoryUrl.starts_with("https://"))
 383       this->RepositoryUrl->insert(0, "https://");
 384   }
 385 }
 386
 387 } // namespace doc
 388 } // namespace clang