From 80e63c17c0a4f02a730b8d00a426fcf0e018f9bb Mon Sep 17 00:00:00 2001 From: Petr Hosek Date: Mon, 3 Feb 2020 12:27:09 -0800 Subject: [PATCH] Revert "[clang-doc] Improving Markdown Output" This reverts commit 0fbaf3a7c2395d751cfa4ecd7f483f077b03d9bd as tests are failing on some bots. --- clang-tools-extra/clang-doc/HTMLGenerator.cpp | 20 +-- clang-tools-extra/clang-doc/MDGenerator.cpp | 166 +++--------------- .../clang-doc/Representation.cpp | 46 ----- clang-tools-extra/clang-doc/Representation.h | 12 -- clang-tools-extra/clang-doc/assets/index.js | 6 +- .../clang-doc/tool/ClangDocMain.cpp | 11 +- 6 files changed, 40 insertions(+), 221 deletions(-) diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp index dc569e2a482c..249d577e8580 100644 --- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp +++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp @@ -314,9 +314,9 @@ genReference(const Reference &Type, StringRef CurrentDirectory, else return genLink(Type.Name, "#" + JumpToSection.getValue()); } - llvm::SmallString<64> Path = Type.getRelativeFilePath(CurrentDirectory); - llvm::sys::path::append(Path, Type.getFileBaseName() + ".html"); - + llvm::SmallString<128> Path = + computeRelativePath(Type.Path, CurrentDirectory); + llvm::sys::path::append(Path, Type.Name + ".html"); // Paths in HTML must be in posix-style llvm::sys::path::native(Path, llvm::sys::path::Style::posix); if (JumpToSection) @@ -730,17 +730,15 @@ genHTML(const NamespaceInfo &I, Index &InfoIndex, const ClangDocContext &CDCtx, if (!I.Description.empty()) Out.emplace_back(genHTML(I.Description)); - llvm::SmallString<64> BasePath = I.getRelativeFilePath(""); - std::vector> ChildNamespaces = - genReferencesBlock(I.ChildNamespaces, "Namespaces", BasePath); + genReferencesBlock(I.ChildNamespaces, "Namespaces", I.Path); AppendVector(std::move(ChildNamespaces), Out); std::vector> ChildRecords = - genReferencesBlock(I.ChildRecords, "Records", BasePath); + genReferencesBlock(I.ChildRecords, "Records", I.Path); AppendVector(std::move(ChildRecords), Out); std::vector> ChildFunctions = - genFunctionsBlock(I.ChildFunctions, CDCtx, BasePath); + genFunctionsBlock(I.ChildFunctions, CDCtx, I.Path); AppendVector(std::move(ChildFunctions), Out); std::vector> ChildEnums = genEnumsBlock(I.ChildEnums, CDCtx); @@ -862,8 +860,8 @@ llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS, "unexpected info type"); } - HTMLFile F = genInfoFile(InfoTitle, I->getRelativeFilePath(""), - MainContentNodes, InfoIndex, CDCtx); + HTMLFile F = + genInfoFile(InfoTitle, I->Path, MainContentNodes, InfoIndex, CDCtx); F.Render(OS); return llvm::Error::success(); @@ -904,7 +902,7 @@ static llvm::Error SerializeIndex(ClangDocContext &CDCtx) { J.attribute("USR", toHex(llvm::toStringRef(I.USR))); J.attribute("Name", I.Name); J.attribute("RefType", getRefType(I.RefType)); - J.attribute("Path", I.getRelativeFilePath("")); + J.attribute("Path", I.Path); J.attributeArray("Children", [&] { for (const Index &C : I.Children) IndexToJSON(C); diff --git a/clang-tools-extra/clang-doc/MDGenerator.cpp b/clang-tools-extra/clang-doc/MDGenerator.cpp index 03af7629127e..ff99c9001349 100644 --- a/clang-tools-extra/clang-doc/MDGenerator.cpp +++ b/clang-tools-extra/clang-doc/MDGenerator.cpp @@ -50,20 +50,10 @@ static void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) { OS << std::string(Num, '#') + " " + Text << "\n\n"; } -static void writeFileDefinition(const ClangDocContext &CDCtx, const Location &L, - raw_ostream &OS) { - - if (!CDCtx.RepositoryUrl) { - OS << "*Defined at " << L.Filename << "#" << std::to_string(L.LineNumber) - << "*"; - } else { - OS << "*Defined at [" << L.Filename << "#" << std::to_string(L.LineNumber) - << "](" << StringRef{CDCtx.RepositoryUrl.getValue()} - << llvm::sys::path::relative_path(L.Filename) << "#" - << std::to_string(L.LineNumber) << ")" - << "*"; - } - OS << "\n\n"; +static void writeFileDefinition(const Location &L, raw_ostream &OS) { + OS << genItalic("Defined at line " + std::to_string(L.LineNumber) + " of " + + L.Filename) + << "\n\n"; } static void writeDescription(const CommentInfo &I, raw_ostream &OS) { @@ -114,16 +104,7 @@ static void writeDescription(const CommentInfo &I, raw_ostream &OS) { } } -static void writeNameLink(const StringRef &CurrentPath, const Reference &R, - llvm::raw_ostream &OS) { - - llvm::SmallString<64> Path = R.getRelativeFilePath(CurrentPath); - llvm::sys::path::append(Path, R.getFileBaseName() + ".md"); - OS << "[" << R.Name << "](" << Path << ")"; -} - -static void genMarkdown(const ClangDocContext &CDCtx, const EnumInfo &I, - llvm::raw_ostream &OS) { +static void genMarkdown(const EnumInfo &I, llvm::raw_ostream &OS) { if (I.Scoped) writeLine("| enum class " + I.Name + " |", OS); else @@ -137,14 +118,13 @@ static void genMarkdown(const ClangDocContext &CDCtx, const EnumInfo &I, Members << "| " << N << " |\n"; writeLine(Members.str(), OS); if (I.DefLoc) - writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS); + writeFileDefinition(I.DefLoc.getValue(), OS); for (const auto &C : I.Description) writeDescription(C, OS); } -static void genMarkdown(const ClangDocContext &CDCtx, const FunctionInfo &I, - llvm::raw_ostream &OS) { +static void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) { std::string Buffer; llvm::raw_string_ostream Stream(Buffer); bool First = true; @@ -165,14 +145,13 @@ static void genMarkdown(const ClangDocContext &CDCtx, const FunctionInfo &I, Stream.str() + ")"), OS); if (I.DefLoc) - writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS); + writeFileDefinition(I.DefLoc.getValue(), OS); for (const auto &C : I.Description) writeDescription(C, OS); } -static void genMarkdown(const ClangDocContext &CDCtx, const NamespaceInfo &I, - llvm::raw_ostream &OS) { +static void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) { if (I.Name == "") writeHeader("Global Namespace", 1, OS); else @@ -185,47 +164,36 @@ static void genMarkdown(const ClangDocContext &CDCtx, const NamespaceInfo &I, writeNewLine(OS); } - llvm::SmallString<64> BasePath = I.getRelativeFilePath(""); - if (!I.ChildNamespaces.empty()) { writeHeader("Namespaces", 2, OS); - for (const auto &R : I.ChildNamespaces) { - OS << "* "; - writeNameLink(BasePath, R, OS); - OS << "\n"; - } + for (const auto &R : I.ChildNamespaces) + writeLine(R.Name, OS); writeNewLine(OS); } - if (!I.ChildRecords.empty()) { writeHeader("Records", 2, OS); - for (const auto &R : I.ChildRecords) { - OS << "* "; - writeNameLink(BasePath, R, OS); - OS << "\n"; - } + for (const auto &R : I.ChildRecords) + writeLine(R.Name, OS); writeNewLine(OS); } - if (!I.ChildFunctions.empty()) { writeHeader("Functions", 2, OS); for (const auto &F : I.ChildFunctions) - genMarkdown(CDCtx, F, OS); + genMarkdown(F, OS); writeNewLine(OS); } if (!I.ChildEnums.empty()) { writeHeader("Enums", 2, OS); for (const auto &E : I.ChildEnums) - genMarkdown(CDCtx, E, OS); + genMarkdown(E, OS); writeNewLine(OS); } } -static void genMarkdown(const ClangDocContext &CDCtx, const RecordInfo &I, - llvm::raw_ostream &OS) { +static void genMarkdown(const RecordInfo &I, llvm::raw_ostream &OS) { writeHeader(getTagType(I.TagType) + " " + I.Name, 1, OS); if (I.DefLoc) - writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS); + writeFileDefinition(I.DefLoc.getValue(), OS); if (!I.Description.empty()) { for (const auto &C : I.Description) @@ -266,86 +234,17 @@ static void genMarkdown(const ClangDocContext &CDCtx, const RecordInfo &I, if (!I.ChildFunctions.empty()) { writeHeader("Functions", 2, OS); for (const auto &F : I.ChildFunctions) - genMarkdown(CDCtx, F, OS); + genMarkdown(F, OS); writeNewLine(OS); } if (!I.ChildEnums.empty()) { writeHeader("Enums", 2, OS); for (const auto &E : I.ChildEnums) - genMarkdown(CDCtx, E, OS); + genMarkdown(E, OS); writeNewLine(OS); } } -static void serializeReference(llvm::raw_fd_ostream &OS, Index &I, int Level) { - // Write out the heading level starting at ## - OS << "##" << std::string(Level, '#') << " "; - writeNameLink("", I, OS); - OS << "\n"; -} - -static llvm::Error serializeIndex(ClangDocContext &CDCtx) { - std::error_code FileErr; - llvm::SmallString<128> FilePath; - llvm::sys::path::native(CDCtx.OutDirectory, FilePath); - llvm::sys::path::append(FilePath, "all_files.md"); - llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None); - if (FileErr) - return llvm::createStringError(llvm::inconvertibleErrorCode(), - "error creating index file: " + - FileErr.message()); - - CDCtx.Idx.sort(); - OS << "# All Files"; - if (!CDCtx.ProjectName.empty()) - OS << " for " << CDCtx.ProjectName; - OS << "\n\n"; - - for (auto C : CDCtx.Idx.Children) - serializeReference(OS, C, 0); - - return llvm::Error::success(); -} - -static llvm::Error genIndex(ClangDocContext &CDCtx) { - std::error_code FileErr; - llvm::SmallString<128> FilePath; - llvm::sys::path::native(CDCtx.OutDirectory, FilePath); - llvm::sys::path::append(FilePath, "index.md"); - llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None); - if (FileErr) - return llvm::createStringError(llvm::inconvertibleErrorCode(), - "error creating index file: " + - FileErr.message()); - CDCtx.Idx.sort(); - OS << "# " << CDCtx.ProjectName << " C/C++ Reference\n\n"; - for (auto C : CDCtx.Idx.Children) { - if (!C.Children.empty()) { - const char *Type; - switch (C.RefType) { - case InfoType::IT_namespace: - Type = "Namespace"; - break; - case InfoType::IT_record: - Type = "Type"; - break; - case InfoType::IT_enum: - Type = "Enum"; - break; - case InfoType::IT_function: - Type = "Function"; - break; - case InfoType::IT_default: - Type = "Other"; - } - OS << "* " << Type << ": [" << C.Name << "]("; - if (!C.Path.empty()) - OS << C.Path << "/"; - OS << C.Name << ")\n"; - } - } - return llvm::Error::success(); -} /// Generator for Markdown documentation. class MDGenerator : public Generator { public: @@ -353,7 +252,6 @@ public: llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS, const ClangDocContext &CDCtx) override; - llvm::Error createResources(ClangDocContext &CDCtx) override; }; const char *MDGenerator::Format = "md"; @@ -362,16 +260,16 @@ llvm::Error MDGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS, const ClangDocContext &CDCtx) { switch (I->IT) { case InfoType::IT_namespace: - genMarkdown(CDCtx, *static_cast(I), OS); + genMarkdown(*static_cast(I), OS); break; case InfoType::IT_record: - genMarkdown(CDCtx, *static_cast(I), OS); + genMarkdown(*static_cast(I), OS); break; case InfoType::IT_enum: - genMarkdown(CDCtx, *static_cast(I), OS); + genMarkdown(*static_cast(I), OS); break; case InfoType::IT_function: - genMarkdown(CDCtx, *static_cast(I), OS); + genMarkdown(*static_cast(I), OS); break; case InfoType::IT_default: return createStringError(llvm::inconvertibleErrorCode(), @@ -380,25 +278,11 @@ llvm::Error MDGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS, return llvm::Error::success(); } -llvm::Error MDGenerator::createResources(ClangDocContext &CDCtx) { - // Write an all_files.md - auto Err = serializeIndex(CDCtx); - if (Err) - return Err; - - // Generate the index page. - Err = genIndex(CDCtx); - if (Err) - return Err; - - return llvm::Error::success(); -} - static GeneratorRegistry::Add MD(MDGenerator::Format, "Generator for MD output."); -// This anchor is used to force the linker to link in the generated object -// file and thus register the generator. +// This anchor is used to force the linker to link in the generated object file +// and thus register the generator. volatile int MDGeneratorAnchorSource = 0; } // namespace doc diff --git a/clang-tools-extra/clang-doc/Representation.cpp b/clang-tools-extra/clang-doc/Representation.cpp index 34d83b438125..56d975af6f40 100644 --- a/clang-tools-extra/clang-doc/Representation.cpp +++ b/clang-tools-extra/clang-doc/Representation.cpp @@ -114,52 +114,6 @@ mergeInfos(std::vector> &Values) { } } -static llvm::SmallString<64> -calculateRelativeFilePath(const InfoType &Type, const StringRef &Path, - const StringRef &Name, const StringRef &CurrentPath) { - llvm::SmallString<64> FilePath; - - if (CurrentPath != Path) { - // iterate back to the top - for (llvm::sys::path::const_iterator I = - llvm::sys::path::begin(CurrentPath); - I != llvm::sys::path::end(CurrentPath); ++I) - llvm::sys::path::append(FilePath, ".."); - llvm::sys::path::append(FilePath, Path); - } - - // Namespace references have a Path to the parent namespace, but - // the file is actually in the subdirectory for the namespace. - if (Type == doc::InfoType::IT_namespace) - llvm::sys::path::append(FilePath, Name); - - return llvm::sys::path::relative_path(FilePath); -} - -llvm::SmallString<64> -Reference::getRelativeFilePath(const StringRef &CurrentPath) const { - return calculateRelativeFilePath(RefType, Path, Name, CurrentPath); -} - -llvm::SmallString<16> Reference::getFileBaseName() const { - if (RefType == InfoType::IT_namespace) - return llvm::SmallString<16>("index"); - - return Name; -} - -llvm::SmallString<64> -Info::getRelativeFilePath(const StringRef &CurrentPath) const { - return calculateRelativeFilePath(IT, Path, extractName(), CurrentPath); -} - -llvm::SmallString<16> Info::getFileBaseName() const { - if (IT == InfoType::IT_namespace) - return llvm::SmallString<16>("index"); - - return extractName(); -} - bool Reference::mergeable(const Reference &Other) { return RefType == Other.RefType && USR == Other.USR; } diff --git a/clang-tools-extra/clang-doc/Representation.h b/clang-tools-extra/clang-doc/Representation.h index ab87b6e45daa..de2993db0abc 100644 --- a/clang-tools-extra/clang-doc/Representation.h +++ b/clang-tools-extra/clang-doc/Representation.h @@ -135,12 +135,6 @@ struct Reference { bool mergeable(const Reference &Other); void merge(Reference &&I); - /// Returns the path for this Reference relative to CurrentPath. - llvm::SmallString<64> getRelativeFilePath(const StringRef &CurrentPath) const; - - /// Returns the basename that should be used for this Reference. - llvm::SmallString<16> getFileBaseName() const; - SymbolID USR = SymbolID(); // Unique identifier for referenced decl SmallString<16> Name; // Name of type (possibly unresolved). InfoType RefType = InfoType::IT_default; // Indicates the type of this @@ -268,12 +262,6 @@ struct Info { llvm::SmallString<16> extractName() const; - /// Returns the file path for this Info relative to CurrentPath. - llvm::SmallString<64> getRelativeFilePath(const StringRef &CurrentPath) const; - - /// Returns the basename that should be used for this Info. - llvm::SmallString<16> getFileBaseName() const; - // Returns a reference to the parent scope (that is, the immediate parent // namespace or class in which this decl resides). llvm::Expected getEnclosingScope(); diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js index 17a476ab6794..32f6556f13e7 100644 --- a/clang-tools-extra/clang-doc/assets/index.js +++ b/clang-tools-extra/clang-doc/assets/index.js @@ -31,11 +31,7 @@ function computeRelativePath(FilePath, CurrentDirectory) { function genLink(Ref, CurrentDirectory) { var Path = computeRelativePath(Ref.Path, CurrentDirectory); - if (Ref.RefType == "namespace") - Path = append(Path, "index.html"); - else - Path = append(Path, Ref.Name + ".html") - + Path = append(Path, Ref.Name + ".html") ANode = document.createElement("a"); ANode.setAttribute("href", Path); var TextNode = document.createTextNode(Ref.Name); diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp index 4c1c5a347362..eae0d84721c4 100644 --- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp +++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp @@ -294,9 +294,8 @@ int main(int argc, const char **argv) { } doc::Info *I = Reduced.get().get(); - auto InfoPath = - getInfoOutputFile(OutDirectory, I->getRelativeFilePath(""), - I->getFileBaseName(), "." + Format); + auto InfoPath = getInfoOutputFile(OutDirectory, I->Path, I->extractName(), + "." + Format); if (!InfoPath) { llvm::errs() << toString(InfoPath.takeError()) << "\n"; Error = true; @@ -305,9 +304,9 @@ int main(int argc, const char **argv) { std::error_code FileErr; llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr, llvm::sys::fs::OF_None); - if (FileErr) { - llvm::errs() << "Error opening info file " << InfoPath.get() << ": " - << FileErr.message() << "\n"; + if (FileErr != OK) { + llvm::errs() << "Error opening info file: " << FileErr.message() + << "\n"; return; }