[clang-doc] Handle anonymous namespaces

[juliehockett]

Summary

Improves output for anonymous decls, and updates the '--public' flag to exclude everything under an anonymous namespace.

[leonardchan]

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

192–215

Nit: Check for Name.empty() early and return Name if it is empty, then have the switch stmt to avoid the repeated conditional expressions.

if (!Name.empty())
  return Name

switch () {
  case InfoType::IT_namespace:
    return llvm::SmallString<16>("GlobalNamespace");
  ...
}

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

282

Should this line be Namespace = N->getNameAsString()?

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

struct Info {
   SmallString<16> Name;                     // Unqualified name of the decl.
   llvm::SmallVector<Reference, 4>
       Namespace; // List of parent namespaces for this decl.
   std::vector<CommentInfo> Description; // Comment description of this decl.
 
   void mergeBase(Info &&I);
   bool mergeable(const Info &Other);
 
+  llvm::SmallString<16> extractName();
+
   // Returns a reference to the parent scope (that is, the immediate parent
   // namespace or class in which this decl resides).
   llvm::Expected<Reference> getEnclosingScope();
 };
 
 // Info for namespaces.
 struct NamespaceInfo : public Info {
   NamespaceInfo() : Info(InfoType::IT_namespace) {}

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

 // all decls related to a given definition. All other fields are ignored in new
 // decls unless the first seen decl didn't, for whatever reason, incorporate
 // data on that field (e.g. a forward declared class wouldn't have information
 // on members on the forward declaration, but would have the class name).
 //
 //===----------------------------------------------------------------------===//
 #include "Representation.h"
 #include "llvm/Support/Error.h"
+#include "llvm/Support/Path.h"
 
 namespace clang {
 namespace doc {
 
 namespace {
 
 const SymbolID EmptySID = SymbolID();
 
if (ReturnType.Type.USR == EmptySID && ReturnType.Type.Name == "")
     ReturnType = std::move(Other.ReturnType);
   if (Parent.USR == EmptySID && Parent.Name == "")
     Parent = std::move(Other.Parent);
   if (Params.empty())
     Params = std::move(Other.Params);
   SymbolInfo::merge(std::move(Other));
 }
 
+llvm::SmallString<16> Info::extractName() {
+  if (!Name.empty())
+    return Name;
+
+  switch (IT) {
+  case InfoType::IT_namespace:
+    // Cover the case where the project contains a base namespace called
+    // 'GlobalNamespace' (i.e. a namespace at the same level as the global
+    // namespace, which would conflict with the hard-coded global namespace name
+    // below.)
+    if (Name == "GlobalNamespace" && Namespace.empty())
+      return llvm::SmallString<16>("@GlobalNamespace");
+    // The case of anonymous namespaces is taken care of in serialization,
+    // so here we can safely assume an unnamed namespace is the global
+    // one.
+    return llvm::SmallString<16>("GlobalNamespace");
+  case InfoType::IT_record:
+    return llvm::SmallString<16>("@nonymous_record_" +
+                                 toHex(llvm::toStringRef(USR)));
+  case InfoType::IT_enum:
+    return llvm::SmallString<16>("@nonymous_enum_" +
+                                 toHex(llvm::toStringRef(USR)));
+  case InfoType::IT_function:
+    return llvm::SmallString<16>("@nonymous_function_" +
+                                 toHex(llvm::toStringRef(USR)));
+  case InfoType::IT_default:
+    return llvm::SmallString<16>("@nonymous_" + toHex(llvm::toStringRef(USR)));
+  }
+  llvm_unreachable("Invalid InfoType.");
+  return llvm::SmallString<16>("");
+}
+
 } // namespace doc
 } // namespace clang

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

for (const CXXBaseSpecifier &B : D->vbases()) {
     else
       I.VirtualParents.emplace_back(B.getType().getAsString());
   }
 }
 
 template <typename T>
 static void
 populateParentNamespaces(llvm::SmallVector<Reference, 4> &Namespaces,
-                         const T *D) {
+                         const T *D, bool &IsAnonymousNamespace) {
   const auto *DC = dyn_cast<DeclContext>(D);
   while ((DC = DC->getParent())) {
-    if (const auto *N = dyn_cast<NamespaceDecl>(DC))
-      Namespaces.emplace_back(getUSRForDecl(N), N->getNameAsString(),
+    if (const auto *N = dyn_cast<NamespaceDecl>(DC)) {
+      std::string Namespace;
+      if (N->isAnonymousNamespace()) {
+        Namespace = "@nonymous_namespace";
+        IsAnonymousNamespace = true;
+      } else
+        Namespace = N->getNameAsString();
+      Namespaces.emplace_back(getUSRForDecl(N), Namespace,
                               InfoType::IT_namespace);
-    else if (const auto *N = dyn_cast<RecordDecl>(DC))
+    } else if (const auto *N = dyn_cast<RecordDecl>(DC))
       Namespaces.emplace_back(getUSRForDecl(N), N->getNameAsString(),
                               InfoType::IT_record);
     else if (const auto *N = dyn_cast<FunctionDecl>(DC))
       Namespaces.emplace_back(getUSRForDecl(N), N->getNameAsString(),
                               InfoType::IT_function);
     else if (const auto *N = dyn_cast<EnumDecl>(DC))
       Namespaces.emplace_back(getUSRForDecl(N), N->getNameAsString(),
                               InfoType::IT_enum);
   }
 }
 
 template <typename T>
-static void populateInfo(Info &I, const T *D, const FullComment *C) {
+static void populateInfo(Info &I, const T *D, const FullComment *C,
+                         bool &IsInAnonymousNamespace) {
   I.USR = getUSRForDecl(D);
   I.Name = D->getNameAsString();
-  populateParentNamespaces(I.Namespace, D);
+  populateParentNamespaces(I.Namespace, D, IsInAnonymousNamespace);
   if (C) {
     I.Description.emplace_back();
     parseFullComment(C, I.Description.back());
   }
 }
 
 template <typename T>
 static void populateSymbolInfo(SymbolInfo &I, const T *D, const FullComment *C,
-                               int LineNumber, StringRef Filename) {
-  populateInfo(I, D, C);
+                               int LineNumber, StringRef Filename,
+                               bool &IsInAnonymousNamespace) {
+  populateInfo(I, D, C, IsInAnonymousNamespace);
   if (D->isThisDeclarationADefinition())
     I.DefLoc.emplace(LineNumber, Filename);
   else
     I.Loc.emplace_back(LineNumber, Filename);
 }
 
 static void populateFunctionInfo(FunctionInfo &I, const FunctionDecl *D,
                                  const FullComment *FC, int LineNumber,
-                                 StringRef Filename) {
-  populateSymbolInfo(I, D, FC, LineNumber, Filename);
+                                 StringRef Filename,
+                                 bool &IsInAnonymousNamespace) {
+  populateSymbolInfo(I, D, FC, LineNumber, Filename, IsInAnonymousNamespace);
   if (const auto *T = getDeclForType(D->getReturnType())) {
     if (dyn_cast<EnumDecl>(T))
       I.ReturnType =
           TypeInfo(getUSRForDecl(T), T->getNameAsString(), InfoType::IT_enum);
     else if (dyn_cast<RecordDecl>(T))
       I.ReturnType =
           TypeInfo(getUSRForDecl(T), T->getNameAsString(), InfoType::IT_record);
   } else {
     I.ReturnType = TypeInfo(D->getReturnType().getAsString());
   }
   parseParameters(I, D);
 }
 
 std::unique_ptr<Info> emitInfo(const NamespaceDecl *D, const FullComment *FC,
                                int LineNumber, llvm::StringRef File,
                                bool PublicOnly) {
-  if (PublicOnly && ((D->isAnonymousNamespace()) ||
+  auto I = llvm::make_unique<NamespaceInfo>();
+  bool IsInAnonymousNamespace = false;
+  populateInfo(*I, D, FC, IsInAnonymousNamespace);
+  if (PublicOnly && ((IsInAnonymousNamespace || D->isAnonymousNamespace()) ||
                      !isPublic(D->getAccess(), D->getLinkageInternal())))
     return nullptr;
-  auto I = llvm::make_unique<NamespaceInfo>();
-  populateInfo(*I, D, FC);
+  I->Name = D->isAnonymousNamespace()
+                ? llvm::SmallString<16>("@nonymous_namespace")
+                : I->Name;
   return std::unique_ptr<Info>{std::move(I)};
 }
 
 std::unique_ptr<Info> emitInfo(const RecordDecl *D, const FullComment *FC,
                                int LineNumber, llvm::StringRef File,
                                bool PublicOnly) {
-  if (PublicOnly && !isPublic(D->getAccess(), D->getLinkageInternal()))
-    return nullptr;
   auto I = llvm::make_unique<RecordInfo>();
-  populateSymbolInfo(*I, D, FC, LineNumber, File);
+  bool IsInAnonymousNamespace = false;
+  populateSymbolInfo(*I, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  if (PublicOnly && ((IsInAnonymousNamespace ||
+                      !isPublic(D->getAccess(), D->getLinkageInternal()))))
+    return nullptr;
+
   I->TagType = D->getTagKind();
   parseFields(*I, D, PublicOnly);
   if (const auto *C = dyn_cast<CXXRecordDecl>(D)) {
     if (const TypedefNameDecl *TD = C->getTypedefNameForAnonDecl()) {
       I->Name = TD->getNameAsString();
       I->IsTypeDef = true;
     }
     parseBases(*I, C);
   }
   return std::unique_ptr<Info>{std::move(I)};
 }
 
 std::unique_ptr<Info> emitInfo(const FunctionDecl *D, const FullComment *FC,
                                int LineNumber, llvm::StringRef File,
                                bool PublicOnly) {
-  if (PublicOnly && !isPublic(D->getAccess(), D->getLinkageInternal()))
-    return nullptr;
   FunctionInfo Func;
-  populateFunctionInfo(Func, D, FC, LineNumber, File);
+  bool IsInAnonymousNamespace = false;
+  populateFunctionInfo(Func, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  if (PublicOnly && ((IsInAnonymousNamespace ||
+                      !isPublic(D->getAccess(), D->getLinkageInternal()))))
+    return nullptr;
+
   Func.Access = clang::AccessSpecifier::AS_none;
 
   // Wrap in enclosing scope
   auto I = llvm::make_unique<NamespaceInfo>();
   if (!Func.Namespace.empty())
     I->USR = Func.Namespace[0].USR;
   else
     I->USR = SymbolID();
   I->ChildFunctions.emplace_back(std::move(Func));
   return std::unique_ptr<Info>{std::move(I)};
 }
 
 std::unique_ptr<Info> emitInfo(const CXXMethodDecl *D, const FullComment *FC,
                                int LineNumber, llvm::StringRef File,
                                bool PublicOnly) {
-  if (PublicOnly && !isPublic(D->getAccess(), D->getLinkageInternal()))
-    return nullptr;
   FunctionInfo Func;
-  populateFunctionInfo(Func, D, FC, LineNumber, File);
+  bool IsInAnonymousNamespace = false;
+  populateFunctionInfo(Func, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  if (PublicOnly && ((IsInAnonymousNamespace ||
+                      !isPublic(D->getAccess(), D->getLinkageInternal()))))
+    return nullptr;
+
   Func.IsMethod = true;
 
   const NamedDecl *Parent = nullptr;
   if (const auto *SD =
           dyn_cast<ClassTemplateSpecializationDecl>(D->getParent()))
     Parent = SD->getSpecializedTemplate();
   else
     Parent = D->getParent();
 
   SymbolID ParentUSR = getUSRForDecl(Parent);
   Func.Parent =
       Reference{ParentUSR, Parent->getNameAsString(), InfoType::IT_record};
   Func.Access = D->getAccess();
 
   // Wrap in enclosing scope
   auto I = llvm::make_unique<RecordInfo>();
   I->USR = ParentUSR;
   I->ChildFunctions.emplace_back(std::move(Func));
   return std::unique_ptr<Info>{std::move(I)};
 }
 
 std::unique_ptr<Info> emitInfo(const EnumDecl *D, const FullComment *FC,
                                int LineNumber, llvm::StringRef File,
                                bool PublicOnly) {
-  if (PublicOnly && !isPublic(D->getAccess(), D->getLinkageInternal()))
-    return nullptr;
   EnumInfo Enum;
-  populateSymbolInfo(Enum, D, FC, LineNumber, File);
+  bool IsInAnonymousNamespace = false;
+  populateSymbolInfo(Enum, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  if (PublicOnly && ((IsInAnonymousNamespace ||
+                      !isPublic(D->getAccess(), D->getLinkageInternal()))))
+    return nullptr;
+
   Enum.Scoped = D->isScoped();
   parseEnumerators(Enum, D);
 
   // Wrap in enclosing scope
   if (!Enum.Namespace.empty()) {
     switch (Enum.Namespace[0].RefType) {
     case InfoType::IT_namespace: {
       auto I = llvm::make_unique<NamespaceInfo>();

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

getInfoOutputFile(StringRef Root,
   llvm::SmallString<128> Path;
   llvm::sys::path::native(Root, Path);
   for (auto R = Namespaces.rbegin(), E = Namespaces.rend(); R != E; ++R)
     llvm::sys::path::append(Path, R->Name);
 
   if (CreateDirectory(Path))
     return llvm::make_error<llvm::StringError>("Unable to create directory.\n",
                                                llvm::inconvertibleErrorCode());
-
-  if (Name.empty())
-    Name = "GlobalNamespace";
   llvm::sys::path::append(Path, Name + Ext);
   return Path;
 }
 
 // Iterate through tool results and build string map of info vectors from the
 // encoded bitstreams.
 bool bitcodeResultsToInfos(
     tooling::ToolResults &Results,
for (auto &Group : USRToInfos) {
     auto Reduced = doc::mergeInfos(Group.getValue());
     if (!Reduced) {
       llvm::errs() << llvm::toString(Reduced.takeError());
       continue;
     }
 
     doc::Info *I = Reduced.get().get();
 
-    auto InfoPath =
-        getInfoOutputFile(OutDirectory, I->Namespace, I->Name, "." + Format);
+    auto InfoPath = getInfoOutputFile(OutDirectory, I->Namespace,
+                                      I->extractName(), "." + Format);
     if (!InfoPath) {
       llvm::errs() << toString(InfoPath.takeError()) << "\n";
       continue;
     }
     std::error_code FileErr;
     llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr, llvm::sys::fs::F_None);
     if (FileErr != OK) {
       llvm::errs() << "Error opening info file: " << FileErr.message() << "\n";

clang-tools-extra/unittests/clang-doc/SerializeTest.cpp

 }
 
 TEST(SerializeTest, emitAnonymousNamespaceInfo) {
   EmittedInfoList Infos;
   ExtractInfosFromCode("namespace { }", 1, /*Public=*/false, Infos);
 
   NamespaceInfo *A = InfoAsNamespace(Infos[0].get());
   NamespaceInfo ExpectedA(EmptySID);
+  ExpectedA.Name = "@nonymous_namespace";
   CheckNamespaceInfo(&ExpectedA, A);
 }
 
 // Test serialization of record declarations.
 TEST(SerializeTest, emitRecordInfo) {
   EmittedInfoList Infos;
   ExtractInfosFromCode(R"raw(class E {
 public: