This is an archive of the discontinued LLVM Phabricator instance.

Differential D63857

[clang-doc] Add a structured HTML generator
ClosedPublic

Authored by DiegoAstiazaran on Jun 26 2019, 5:31 PM.

Details

Reviewers
juliehockett
jakehehrlich
lebedev.ri
Commits
rG671bac743673: [clang-doc] Add a structured HTML generator
rCTE365687: [clang-doc] Add a structured HTML generator
rL365687: [clang-doc] Add a structured HTML generator
Summary

Implements an HTML generator.
Nodes are used to represent each part of the HTML file. There are TagNodes that represent every HTML tag (p, h1, div, ...) and they have children nodes, which can be TagNodes or TextNodes (these nodes only have text).
Proper indentation is rendered within the files generated by tool.
No styling (CSS) is included.

Diff Detail

Event Timeline

DiegoAstiazaran created this revision.Jun 26 2019, 5:31 PM
juliehockett added inline comments.Jun 26 2019, 6:00 PM
clang-tools-extra/clang-doc/HTMLGenerator.cpp
21

Put the class definitions in an anonymous namespace (https://llvm.org/docs/CodingStandards.html#anonymous-namespaces)

24

Use TagType or some such to avoid confusion with the containing class

25–33

Enum values should be capitalized, and probably prefixed with HTML_ or TAG_ or some such useful prefix (e.g. TAG_META)

42

For this and other functions, separate the implementation from the definition.

121
TagNode(HTMLTag Tag) : Tag(Tag), InlineChildren(Tag.HasInlineChildren), SelfClosing(Tag.SelfClosing) {}
412

use emplace_back here for instantiation

clang-tools-extra/clang-doc/MDGenerator.cpp
30–31

Can you re-static these?

DiegoAstiazaran updated this revision to Diff 206920.Jun 27 2019, 1:27 PM
DiegoAstiazaran marked 7 inline comments as done.

Fix TagType enum name and members.
Add anonymous namespace.
Separate the implementation from the definition for some functions.
Use emplace_back instead of push_back for instantiation of vector members.

jakehehrlich added a comment.Jun 27 2019, 2:31 PM

Overall looks better. One of my comments causes a sweeping change to occur so I'll respond back after thats done.

clang-tools-extra/clang-doc/HTMLGenerator.cpp
91

Does this ever change? If not this should be a global constexpr constant char* inside of an anon-namespace.

e.g.

namespace {

constexpr const char* kDoctypeDecl = "...";

}

170

You can exit here if its self closing right?

187

You should return TagNodes, not assign to them by ref. Preferably via retruning a unique pointer. It doesn't make sense to have the consumer do the constructor I would imagine. For instance what tag is the right tag type? The consumer shouldn't decide, the producer should.

190

Same comment here these function should look like (at a very high an imprecise level, obviously some functions will be more complicated.)

std::unique_ptr<TagNode> genFoo(info) {
  auto out = llvm::make_unique<...>(...);
  for (const auto &B : info.bars)
    out->Children.emplace_back(genBar(B));
  return out;
}

This goes for all of these functions

DiegoAstiazaran mentioned this in D63666: [clang-doc] Add templates to HTML generator.Jun 28 2019, 12:16 PM
DiegoAstiazaran updated this revision to Diff 207148.Jun 28 2019, 2:54 PM
DiegoAstiazaran marked 6 inline comments as done.

Make DoctypeDecl a constexpr.
Early exit in TagNode::Render.
Functions of HTMLGenerator now return HTMLNodes instead of adding children to a Node passed by reference.

clang-tools-extra/clang-doc/HTMLGenerator.cpp
91

In HTML5 it's always <!DOCTYPE html> so I've already changed it in the latest patch.

170

Yes, fixed in the latest patch update.

jakehehrlich added a comment.Jun 28 2019, 3:29 PM

Can you upload git diff -U100000 <commit before genHTML> functions so that I can see the code without it being fragmented? It's hard to parse some of the more fragmented stuff here

clang-tools-extra/clang-doc/HTMLGenerator.cpp
191–194

Never use 'static' for functions in C++. For functions anon-namespaces and 'static' mean the same thing but C++ generates a lot of stuff behind the scenes and to make those 'static' you need to use an non-namespace.

In general the rule is to put as much as you can in anon-namespaces and always prefer that for functions/globals/constants over 'static'. This is important for constexpr variables specifically because depending on the C++ version they don't play nice with the static keyword.

DiegoAstiazaran mentioned this in D63180: [clang-doc] Adds HTML generator.Jun 28 2019, 3:35 PM
DiegoAstiazaran updated this revision to Diff 207160.Jun 28 2019, 3:41 PM
DiegoAstiazaran retitled this revision from [clang-doc] Structured HTML generator to [clang-doc] Add a structured HTML generator.
DiegoAstiazaran edited the summary of this revision. (Show Details)

This patch depended on D63180, that revision has been abandoned and combined with this one.

Herald added subscribers: kadircet, arphaman, mgorny. · View Herald TranscriptJun 28 2019, 3:41 PM
jakehehrlich added inline comments.Jun 28 2019, 3:42 PM
clang-tools-extra/clang-doc/HTMLGenerator.cpp
228

Refering to this as Out.back() is confusing, can you give it a variable name? It took me longer than I care to admit to figure out that you weren't appending to Out in the loop. A pretty common pattern I use is to just assign back() to a reference that I'm going to use a lot.

Out.emplace_back(...);
auto& DivBody = Out.back();

That way you get the inplace construction and you can refer to it wherever you'd like by name.

DiegoAstiazaran updated this revision to Diff 207174.Jun 28 2019, 4:31 PM
DiegoAstiazaran marked 2 inline comments as done.

Add a variable to use as a reference to the last item in a vector instead of doing vector.back().

DiegoAstiazaran added a child revision: D63663: [clang-doc] Add html links to references.Jul 2 2019, 1:02 PM
jakehehrlich added a comment.Jul 8 2019, 1:21 PM

This looks good to me!

clang-tools-extra/clang-doc/Generators.cpp
75–78

I don't fully understand these lines. Can you explain how they work and what they accomplish?

clang-tools-extra/clang-doc/HTMLGenerator.cpp
76

I think you can just write Children.emplace_back(Text.str(), !InlineChildren)

311–313
for (...)  
  if (std::unique)ptr<...> Node = genHTML(Child))
    CommentBlock->...

would be a bitmore idiomatic LLVM code. I think you used this pattern above as well so you should fix it there as well.

326

same thing here I think.

359

ditto

423

ditto

426

ditto

429

ditto

433–435

You use this a lot here and once or twice above. You could write a template function that takes an std::vector<B>&& and moves its contents into some other std::vector<A>& where B : A

You can use SFINAE to ensure that B is subtype of A.

473–476

These are all cases of what I was talking about before.

506

ditto.

508

Use emplace_back when moving to avoid extra constructor calls.

jakehehrlich added a comment.Jul 8 2019, 1:21 PM

As in I'm not quite ready for this to land but It looks preety solid. I think if you respond to those comments I'll take one last look and then give an actual accept

DiegoAstiazaran updated this revision to Diff 208527.Jul 8 2019, 3:42 PM
DiegoAstiazaran marked 5 inline comments as done.

Add helper function to move a vector's elements to another vector.

clang-tools-extra/clang-doc/HTMLGenerator.cpp
76

I think it is necessary to explicitly pass a unique_ptr, not only the args.

juliehockett accepted this revision.Jul 9 2019, 9:01 AM

LGTM, unless Jake has further comments.

clang-tools-extra/clang-doc/HTMLGenerator.cpp
504

Remove this

This revision is now accepted and ready to land.Jul 9 2019, 9:01 AM
DiegoAstiazaran updated this revision to Diff 208739.Jul 9 2019, 10:53 AM
DiegoAstiazaran marked an inline comment as done.

Remove empty line.

DiegoAstiazaran updated this revision to Diff 208792.Jul 9 2019, 1:14 PM
Closed by commit rL365687: [clang-doc] Add a structured HTML generator (authored by juliehockett). · Explain WhyJul 10 2019, 12:04 PM
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptJul 10 2019, 12:04 PM
Herald added a subscriber: llvm-commits. · View Herald Transcript

Revision Contents

PathSize
clang-tools-extra/
clang-doc/
1 line
6 lines
48 lines
517 lines
69 lines
tool/
7 lines
unittests/
clang-doc/
1 line
276 lines

Diff 208739

clang-tools-extra/clang-doc/CMakeLists.txt

set(LLVM_LINK_COMPONENTS set(LLVM_LINK_COMPONENTS
support support
BitReader BitReader
BitWriter BitWriter
) )
add_clang_library(clangDoc add_clang_library(clangDoc
BitcodeReader.cpp BitcodeReader.cpp
BitcodeWriter.cpp BitcodeWriter.cpp
ClangDoc.cpp ClangDoc.cpp
Generators.cpp Generators.cpp
HTMLGenerator.cpp
Mapper.cpp Mapper.cpp
MDGenerator.cpp MDGenerator.cpp
Representation.cpp Representation.cpp
Serialize.cpp Serialize.cpp
YAMLGenerator.cpp YAMLGenerator.cpp
LINK_LIBS LINK_LIBS
clangAnalysis clangAnalysis
Show All 11 Lines

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

Show All 28 Linespublic:
virtual llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) = 0; virtual llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) = 0;
}; };
typedef llvm::Registry<Generator> GeneratorRegistry; typedef llvm::Registry<Generator> GeneratorRegistry;
llvm::Expected<std::unique_ptr<Generator>> llvm::Expected<std::unique_ptr<Generator>>
findGeneratorByName(llvm::StringRef Format); findGeneratorByName(llvm::StringRef Format);
std::string getAccess(AccessSpecifier AS);
std::string getTagType(TagTypeKind AS);
std::string genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs);
} // namespace doc } // namespace doc
} // namespace clang } // namespace clang
#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_GENERATOR_H #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_GENERATOR_H

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

Show All 19 Lines for (auto I = GeneratorRegistry::begin(), E = GeneratorRegistry::end();
if (I->getName() != Format) if (I->getName() != Format)
continue; continue;
return I->instantiate(); return I->instantiate();
} }
return llvm::make_error<llvm::StringError>("Can't find generator: " + Format, return llvm::make_error<llvm::StringError>("Can't find generator: " + Format,
llvm::inconvertibleErrorCode()); llvm::inconvertibleErrorCode());
} }
// Enum conversion
std::string getAccess(AccessSpecifier AS) {
switch (AS) {
case AccessSpecifier::AS_public:
return "public";
case AccessSpecifier::AS_protected:
return "protected";
case AccessSpecifier::AS_private:
return "private";
case AccessSpecifier::AS_none:
return {};
}
llvm_unreachable("Unknown AccessSpecifier");
}
std::string getTagType(TagTypeKind AS) {
switch (AS) {
case TagTypeKind::TTK_Class:
return "class";
case TagTypeKind::TTK_Union:
return "union";
case TagTypeKind::TTK_Interface:
return "interface";
case TagTypeKind::TTK_Struct:
return "struct";
case TagTypeKind::TTK_Enum:
return "enum";
}
llvm_unreachable("Unknown TagTypeKind");
}
// Generates a comma-separated list of Refs
// Used to display the parents of a record
std::string genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs) {
std::string Buffer;
llvm::raw_string_ostream Stream(Buffer);
for (const auto &R : Refs) {
if (&R != Refs.begin())
Stream << ", ";
Stream << R.Name;
}
return Stream.str();
}
// This anchor is used to force the linker to link in the generated object file // This anchor is used to force the linker to link in the generated object file
// and thus register the generators. // and thus register the generators.
extern volatile int YAMLGeneratorAnchorSource; extern volatile int YAMLGeneratorAnchorSource;
extern volatile int MDGeneratorAnchorSource; extern volatile int MDGeneratorAnchorSource;
extern volatile int HTMLGeneratorAnchorSource;
static int LLVM_ATTRIBUTE_UNUSED YAMLGeneratorAnchorDest = static int LLVM_ATTRIBUTE_UNUSED YAMLGeneratorAnchorDest =
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

I don't fully understand these lines. Can you explain how they work and what they accomplish?

jakehehrlich: I don't fully understand these lines. Can you explain how they work and what they accomplish?
YAMLGeneratorAnchorSource; YAMLGeneratorAnchorSource;
static int LLVM_ATTRIBUTE_UNUSED MDGeneratorAnchorDest = static int LLVM_ATTRIBUTE_UNUSED MDGeneratorAnchorDest =
MDGeneratorAnchorSource; MDGeneratorAnchorSource;
static int LLVM_ATTRIBUTE_UNUSED HTMLGeneratorAnchorDest =
HTMLGeneratorAnchorSource;
} // namespace doc } // namespace doc
} // namespace clang } // namespace clang

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

  • This file was added.
//===-- HTMLGenerator.cpp - HTML Generator ----------------------*- 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 "Generators.h"
#include "Representation.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/Support/FileSystem.h"
#include "llvm/Support/Path.h"
#include <string>
using namespace llvm;
namespace clang {
namespace doc {
template <typename Derived, typename Base,
juliehockettUnsubmitted
Done
ReplyInline Actions

Put the class definitions in an anonymous namespace (https://llvm.org/docs/CodingStandards.html#anonymous-namespaces)

juliehockett: Put the class definitions in an anonymous namespace (https://llvm.org/docs/CodingStandards.
typename = std::enable_if<std::is_base_of<Derived, Base>::value>>
static void AppendVector(std::vector<Derived> &&New,
std::vector<Base> &Original) {
juliehockettUnsubmitted
Done
ReplyInline Actions

Use TagType or some such to avoid confusion with the containing class

juliehockett: Use `TagType` or some such to avoid confusion with the containing class
std::move(New.begin(), New.end(), std::back_inserter(Original));
}
namespace {
class HTMLTag {
public:
// Any other tag can be added if required
enum TagType {
juliehockettUnsubmitted
Done
ReplyInline Actions

Enum values should be capitalized, and probably prefixed with HTML_ or TAG_ or some such useful prefix (e.g. TAG_META)

juliehockett: Enum values should be capitalized, and probably prefixed with HTML_ or TAG_ or some such useful…
TAG_META,
TAG_TITLE,
TAG_DIV,
TAG_H1,
TAG_H2,
TAG_H3,
TAG_P,
TAG_UL,
TAG_LI,
juliehockettUnsubmitted
Done
ReplyInline Actions

For this and other functions, separate the implementation from the definition.

juliehockett: For this and other functions, separate the implementation from the definition.
};
HTMLTag() = default;
constexpr HTMLTag(TagType Value) : Value(Value) {}
operator TagType() const { return Value; }
operator bool() = delete;
bool IsSelfClosing() const;
bool HasInlineChildren() const;
llvm::SmallString<16> ToString() const;
private:
TagType Value;
};
struct HTMLNode {
virtual ~HTMLNode() = default;
virtual void Render(llvm::raw_ostream &OS, int IndentationLevel) = 0;
};
struct TextNode : public HTMLNode {
TextNode(llvm::StringRef Text, bool Indented)
: Text(Text), Indented(Indented) {}
std::string Text; // Content of node
bool Indented; // Indicates if an indentation must be rendered before the text
void Render(llvm::raw_ostream &OS, int IndentationLevel) override;
};
struct TagNode : public HTMLNode {
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

I think you can just write Children.emplace_back(Text.str(), !InlineChildren)

jakehehrlich: I think you can just write `Children.emplace_back(Text.str(), !InlineChildren)`
DiegoAstiazaranAuthorUnsubmitted
Done
ReplyInline Actions

I think it is necessary to explicitly pass a unique_ptr, not only the args.

DiegoAstiazaran: I think it is necessary to explicitly pass a unique_ptr, not only the args.
TagNode(HTMLTag Tag)
: Tag(Tag), InlineChildren(Tag.HasInlineChildren()),
SelfClosing(Tag.IsSelfClosing()) {}
TagNode(HTMLTag Tag, const Twine &Text) : TagNode(Tag) {
Children.emplace_back(
llvm::make_unique<TextNode>(Text.str(), !InlineChildren));
}
HTMLTag Tag; // Name of HTML Tag (p, div, h1)
bool InlineChildren; // Indicates if children nodes are rendered in the same
// line as itself or if children must rendered in the
// next line and with additional indentation
bool SelfClosing; // Indicates if tag is self-closing
std::vector<std::unique_ptr<HTMLNode>> Children; // List of child nodes
llvm::StringMap<llvm::SmallString<16>>
jakehehrlichUnsubmitted
Done
ReplyInline Actions

Does this ever change? If not this should be a global constexpr constant char* inside of an anon-namespace.

e.g.

namespace {

constexpr const char* kDoctypeDecl = "...";

}

jakehehrlich: Does this ever change? If not this should be a global constexpr constant char* inside of an…
DiegoAstiazaranAuthorUnsubmitted
Done
ReplyInline Actions

In HTML5 it's always <!DOCTYPE html> so I've already changed it in the latest patch.

DiegoAstiazaran: In HTML5 it's always `<!DOCTYPE html>` so I've already changed it in the latest patch.
Attributes; // List of key-value attributes for tag
void Render(llvm::raw_ostream &OS, int IndentationLevel) override;
};
constexpr const char *kDoctypeDecl = "<!DOCTYPE html>";
struct HTMLFile {
std::vector<std::unique_ptr<HTMLNode>> Children; // List of child nodes
void Render(llvm::raw_ostream &OS) {
OS << kDoctypeDecl << "\n";
for (const auto &C : Children) {
C->Render(OS, 0);
OS << "\n";
}
}
};
} // namespace
bool HTMLTag::IsSelfClosing() const {
switch (Value) {
case HTMLTag::TAG_META:
return true;
case HTMLTag::TAG_TITLE:
case HTMLTag::TAG_DIV:
case HTMLTag::TAG_H1:
case HTMLTag::TAG_H2:
case HTMLTag::TAG_H3:
case HTMLTag::TAG_P:
juliehockettUnsubmitted
Done
ReplyInline Actions
TagNode(HTMLTag Tag) : Tag(Tag), InlineChildren(Tag.HasInlineChildren), SelfClosing(Tag.SelfClosing) {}
juliehockett: ```TagNode(HTMLTag Tag) : Tag(Tag), InlineChildren(Tag.HasInlineChildren), SelfClosing(Tag.
case HTMLTag::TAG_UL:
case HTMLTag::TAG_LI:
return false;
}
}
bool HTMLTag::HasInlineChildren() const {
switch (Value) {
case HTMLTag::TAG_META:
case HTMLTag::TAG_TITLE:
case HTMLTag::TAG_H1:
case HTMLTag::TAG_H2:
case HTMLTag::TAG_H3:
case HTMLTag::TAG_LI:
return true;
case HTMLTag::TAG_DIV:
case HTMLTag::TAG_P:
case HTMLTag::TAG_UL:
return false;
}
}
llvm::SmallString<16> HTMLTag::ToString() const {
switch (Value) {
case HTMLTag::TAG_META:
return llvm::SmallString<16>("meta");
case HTMLTag::TAG_TITLE:
return llvm::SmallString<16>("title");
case HTMLTag::TAG_DIV:
return llvm::SmallString<16>("div");
case HTMLTag::TAG_H1:
return llvm::SmallString<16>("h1");
case HTMLTag::TAG_H2:
return llvm::SmallString<16>("h2");
case HTMLTag::TAG_H3:
return llvm::SmallString<16>("h3");
case HTMLTag::TAG_P:
return llvm::SmallString<16>("p");
case HTMLTag::TAG_UL:
return llvm::SmallString<16>("ul");
case HTMLTag::TAG_LI:
return llvm::SmallString<16>("li");
}
}
void TextNode::Render(llvm::raw_ostream &OS, int IndentationLevel) {
if (Indented)
OS.indent(IndentationLevel * 2);
OS << Text;
jakehehrlichUnsubmitted
Done
ReplyInline Actions

You can exit here if its self closing right?

jakehehrlich: You can exit here if its self closing right?
DiegoAstiazaranAuthorUnsubmitted
Done
ReplyInline Actions

Yes, fixed in the latest patch update.

DiegoAstiazaran: Yes, fixed in the latest patch update.
}
void TagNode::Render(llvm::raw_ostream &OS, int IndentationLevel) {
OS.indent(IndentationLevel * 2);
OS << "<" << Tag.ToString();
for (const auto &A : Attributes)
OS << " " << A.getKey() << "=\"" << A.getValue() << "\"";
if (SelfClosing) {
OS << "/>";
return;
}
OS << ">";
if (!InlineChildren)
OS << "\n";
int ChildrenIndentation = InlineChildren ? 0 : IndentationLevel + 1;
for (const auto &C : Children) {
C->Render(OS, ChildrenIndentation);
jakehehrlichUnsubmitted
Done
ReplyInline Actions

You should return TagNodes, not assign to them by ref. Preferably via retruning a unique pointer. It doesn't make sense to have the consumer do the constructor I would imagine. For instance what tag is the right tag type? The consumer shouldn't decide, the producer should.

jakehehrlich: You should return TagNodes, not assign to them by ref. Preferably via retruning a unique…
if (!InlineChildren)
OS << "\n";
}
jakehehrlichUnsubmitted
Done
ReplyInline Actions

Same comment here these function should look like (at a very high an imprecise level, obviously some functions will be more complicated.)

std::unique_ptr<TagNode> genFoo(info) {
  auto out = llvm::make_unique<...>(...);
  for (const auto &B : info.bars)
    out->Children.emplace_back(genBar(B));
  return out;
}

This goes for all of these functions

jakehehrlich: Same comment here these function should look like (at a very high an imprecise level, obviously…
if (!InlineChildren)
OS.indent(IndentationLevel * 2);
OS << "</" << Tag.ToString() << ">";
}
jakehehrlichUnsubmitted
Done
ReplyInline Actions

Never use 'static' for functions in C++. For functions anon-namespaces and 'static' mean the same thing but C++ generates a lot of stuff behind the scenes and to make those 'static' you need to use an non-namespace.

In general the rule is to put as much as you can in anon-namespaces and always prefer that for functions/globals/constants over 'static'. This is important for constexpr variables specifically because depending on the C++ version they don't play nice with the static keyword.

jakehehrlich: Never use 'static' for functions in C++. For functions anon-namespaces and 'static' mean the…
// HTML generation
static std::vector<std::unique_ptr<TagNode>> genHTML(const EnumInfo &I);
static std::vector<std::unique_ptr<TagNode>> genHTML(const FunctionInfo &I);
static std::vector<std::unique_ptr<TagNode>>
genEnumsBlock(const std::vector<EnumInfo> &Enums) {
if (Enums.empty())
return {};
std::vector<std::unique_ptr<TagNode>> Out;
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, "Enums"));
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_DIV));
auto &DivBody = Out.back();
for (const auto &E : Enums) {
std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(E);
AppendVector(std::move(Nodes), DivBody->Children);
}
return Out;
}
static std::unique_ptr<TagNode>
genEnumMembersBlock(const llvm::SmallVector<SmallString<16>, 4> &Members) {
if (Members.empty())
return nullptr;
auto List = llvm::make_unique<TagNode>(HTMLTag::TAG_UL);
for (const auto &M : Members)
List->Children.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_LI, M));
return List;
}
static std::vector<std::unique_ptr<TagNode>>
jakehehrlichUnsubmitted
Done
ReplyInline Actions

Refering to this as Out.back() is confusing, can you give it a variable name? It took me longer than I care to admit to figure out that you weren't appending to Out in the loop. A pretty common pattern I use is to just assign back() to a reference that I'm going to use a lot.

Out.emplace_back(...);
auto& DivBody = Out.back();

That way you get the inplace construction and you can refer to it wherever you'd like by name.

jakehehrlich: Refering to this as `Out.back()` is confusing, can you give it a variable name? It took me…
genFunctionsBlock(const std::vector<FunctionInfo> &Functions) {
if (Functions.empty())
return {};
std::vector<std::unique_ptr<TagNode>> Out;
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, "Functions"));
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_DIV));
auto &DivBody = Out.back();
for (const auto &F : Functions) {
std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(F);
AppendVector(std::move(Nodes), DivBody->Children);
}
return Out;
}
static std::vector<std::unique_ptr<TagNode>>
genRecordMembersBlock(const llvm::SmallVector<MemberTypeInfo, 4> &Members) {
if (Members.empty())
return {};
std::vector<std::unique_ptr<TagNode>> Out;
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, "Members"));
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_UL));
auto &ULBody = Out.back();
for (const auto &M : Members) {
std::string Access = getAccess(M.Access);
if (Access != "")
Access = Access + " ";
ULBody->Children.emplace_back(llvm::make_unique<TagNode>(
HTMLTag::TAG_LI, Access + M.Type.Name + " " + M.Name));
}
return Out;
}
static std::vector<std::unique_ptr<TagNode>>
genReferencesBlock(const std::vector<Reference> &References,
llvm::StringRef Title) {
if (References.empty())
return {};
std::vector<std::unique_ptr<TagNode>> Out;
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, Title));
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_UL));
auto &ULBody = Out.back();
for (const auto &R : References)
ULBody->Children.emplace_back(
llvm::make_unique<TagNode>(HTMLTag::TAG_LI, R.Name));
return Out;
}
static std::unique_ptr<TagNode> writeFileDefinition(const Location &L) {
return llvm::make_unique<TagNode>(
HTMLTag::TAG_P,
"Defined at line " + std::to_string(L.LineNumber) + " of " + L.Filename);
}
static std::unique_ptr<HTMLNode> genHTML(const CommentInfo &I) {
if (I.Kind == "FullComment") {
auto FullComment = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
for (const auto &Child : I.Children) {
std::unique_ptr<HTMLNode> Node = genHTML(*Child);
if (Node)
FullComment->Children.emplace_back(std::move(Node));
}
return std::move(FullComment);
} else if (I.Kind == "ParagraphComment") {
auto ParagraphComment = llvm::make_unique<TagNode>(HTMLTag::TAG_P);
for (const auto &Child : I.Children) {
std::unique_ptr<HTMLNode> Node = genHTML(*Child);
if (Node)
ParagraphComment->Children.emplace_back(std::move(Node));
}
if (ParagraphComment->Children.empty())
return nullptr;
return std::move(ParagraphComment);
} else if (I.Kind == "TextComment") {
if (I.Text == "")
return nullptr;
return llvm::make_unique<TextNode>(I.Text, true);
}
return nullptr;
}
static std::unique_ptr<TagNode> genHTML(const std::vector<CommentInfo> &C) {
auto CommentBlock = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
jakehehrlichUnsubmitted
Done
ReplyInline Actions
for (...)  
  if (std::unique)ptr<...> Node = genHTML(Child))
    CommentBlock->...

would be a bitmore idiomatic LLVM code. I think you used this pattern above as well so you should fix it there as well.

jakehehrlich: ``` for (...) if (std::unique)ptr<...> Node = genHTML(Child)) CommentBlock->... ```…
for (const auto &Child : C) {
if (std::unique_ptr<HTMLNode> Node = genHTML(Child))
CommentBlock->Children.emplace_back(std::move(Node));
}
return CommentBlock;
}
static std::vector<std::unique_ptr<TagNode>> genHTML(const EnumInfo &I) {
std::vector<std::unique_ptr<TagNode>> Out;
std::string EnumType;
if (I.Scoped)
EnumType = "enum class ";
else
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

same thing here I think.

jakehehrlich: same thing here I think.
EnumType = "enum ";
Out.emplace_back(
llvm::make_unique<TagNode>(HTMLTag::TAG_H3, EnumType + I.Name));
std::unique_ptr<TagNode> Node = genEnumMembersBlock(I.Members);
if (Node)
Out.emplace_back(std::move(Node));
if (I.DefLoc)
Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
std::string Description;
if (!I.Description.empty())
Out.emplace_back(genHTML(I.Description));
return Out;
}
static std::vector<std::unique_ptr<TagNode>> genHTML(const FunctionInfo &I) {
std::vector<std::unique_ptr<TagNode>> Out;
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H3, I.Name));
std::string Buffer;
llvm::raw_string_ostream Stream(Buffer);
for (const auto &P : I.Params) {
if (&P != I.Params.begin())
Stream << ", ";
Stream << P.Type.Name + " " + P.Name;
}
std::string Access = getAccess(I.Access);
if (Access != "")
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

ditto

jakehehrlich: ditto
Access = Access + " ";
Out.emplace_back(llvm::make_unique<TagNode>(
HTMLTag::TAG_P, Access + I.ReturnType.Type.Name + " " + I.Name + "(" +
Stream.str() + ")"));
if (I.DefLoc)
Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
std::string Description;
if (!I.Description.empty())
Out.emplace_back(genHTML(I.Description));
return Out;
}
static std::vector<std::unique_ptr<TagNode>> genHTML(const NamespaceInfo &I,
std::string &InfoTitle) {
std::vector<std::unique_ptr<TagNode>> Out;
if (I.Name.str() == "")
InfoTitle = "Global Namespace";
else
InfoTitle = ("namespace " + I.Name).str();
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
std::string Description;
if (!I.Description.empty())
Out.emplace_back(genHTML(I.Description));
std::vector<std::unique_ptr<TagNode>> ChildNamespaces =
genReferencesBlock(I.ChildNamespaces, "Namespaces");
AppendVector(std::move(ChildNamespaces), Out);
std::vector<std::unique_ptr<TagNode>> ChildRecords =
genReferencesBlock(I.ChildRecords, "Records");
AppendVector(std::move(ChildRecords), Out);
std::vector<std::unique_ptr<TagNode>> ChildFunctions =
genFunctionsBlock(I.ChildFunctions);
AppendVector(std::move(ChildFunctions), Out);
std::vector<std::unique_ptr<TagNode>> ChildEnums =
genEnumsBlock(I.ChildEnums);
AppendVector(std::move(ChildEnums), Out);
return Out;
}
static std::vector<std::unique_ptr<TagNode>> genHTML(const RecordInfo &I,
std::string &InfoTitle) {
std::vector<std::unique_ptr<TagNode>> Out;
InfoTitle = (getTagType(I.TagType) + " " + I.Name).str();
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
juliehockettUnsubmitted
Done
ReplyInline Actions

use emplace_back here for instantiation

juliehockett: use `emplace_back` here for instantiation
if (I.DefLoc)
Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
std::string Description;
if (!I.Description.empty())
Out.emplace_back(genHTML(I.Description));
std::string Parents = genReferenceList(I.Parents);
std::string VParents = genReferenceList(I.VirtualParents);
if (!Parents.empty() || !VParents.empty()) {
if (Parents.empty())
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

ditto

jakehehrlich: ditto
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_P,
"Inherits from " + VParents));
else if (VParents.empty())
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

ditto

jakehehrlich: ditto
Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_P,
"Inherits from " + Parents));
else
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

ditto

jakehehrlich: ditto
Out.emplace_back(llvm::make_unique<TagNode>(
HTMLTag::TAG_P, "Inherits from " + Parents + ", " + VParents));
}
std::vector<std::unique_ptr<TagNode>> Members =
genRecordMembersBlock(I.Members);
jakehehrlichUnsubmitted
Done
ReplyInline Actions

You use this a lot here and once or twice above. You could write a template function that takes an std::vector<B>&& and moves its contents into some other std::vector<A>& where B : A

You can use SFINAE to ensure that B is subtype of A.

jakehehrlich: You use this a lot here and once or twice above. You could write a template function that takes…
AppendVector(std::move(Members), Out);
std::vector<std::unique_ptr<TagNode>> ChildRecords =
genReferencesBlock(I.ChildRecords, "Records");
AppendVector(std::move(ChildRecords), Out);
std::vector<std::unique_ptr<TagNode>> ChildFunctions =
genFunctionsBlock(I.ChildFunctions);
AppendVector(std::move(ChildFunctions), Out);
std::vector<std::unique_ptr<TagNode>> ChildEnums =
genEnumsBlock(I.ChildEnums);
AppendVector(std::move(ChildEnums), Out);
return Out;
}
/// Generator for HTML documentation.
class HTMLGenerator : public Generator {
public:
static const char *Format;
llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) override;
};
const char *HTMLGenerator::Format = "html";
llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS) {
HTMLFile F;
auto MetaNode = llvm::make_unique<TagNode>(HTMLTag::TAG_META);
MetaNode->Attributes.try_emplace("charset", "utf-8");
F.Children.emplace_back(std::move(MetaNode));
std::string InfoTitle;
Info CastedInfo;
auto MainContentNode = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
switch (I->IT) {
case InfoType::IT_namespace: {
std::vector<std::unique_ptr<TagNode>> Nodes =
genHTML(*static_cast<clang::doc::NamespaceInfo *>(I), InfoTitle);
AppendVector(std::move(Nodes), MainContentNode->Children);
break;
jakehehrlichUnsubmitted
Done
ReplyInline Actions

These are all cases of what I was talking about before.

jakehehrlich: These are all cases of what I was talking about before.
}
case InfoType::IT_record: {
std::vector<std::unique_ptr<TagNode>> Nodes =
genHTML(*static_cast<clang::doc::RecordInfo *>(I), InfoTitle);
AppendVector(std::move(Nodes), MainContentNode->Children);
break;
}
case InfoType::IT_enum: {
std::vector<std::unique_ptr<TagNode>> Nodes =
genHTML(*static_cast<clang::doc::EnumInfo *>(I));
AppendVector(std::move(Nodes), MainContentNode->Children);
break;
}
case InfoType::IT_function: {
std::vector<std::unique_ptr<TagNode>> Nodes =
genHTML(*static_cast<clang::doc::FunctionInfo *>(I));
AppendVector(std::move(Nodes), MainContentNode->Children);
break;
}
case InfoType::IT_default:
return llvm::make_error<llvm::StringError>("Unexpected info type.\n",
llvm::inconvertibleErrorCode());
}
F.Children.emplace_back(
llvm::make_unique<TagNode>(HTMLTag::TAG_TITLE, InfoTitle));
F.Children.emplace_back(std::move(MainContentNode));
F.Render(OS);
juliehockettUnsubmitted
Done
ReplyInline Actions

Remove this

juliehockett: Remove this
return llvm::Error::success();
jakehehrlichUnsubmitted
Not Done
ReplyInline Actions

ditto.

jakehehrlich: ditto.
}
jakehehrlichUnsubmitted
Done
ReplyInline Actions

Use emplace_back when moving to avoid extra constructor calls.

jakehehrlich: Use `emplace_back` when moving to avoid extra constructor calls.
static GeneratorRegistry::Add<HTMLGenerator> HTML(HTMLGenerator::Format,
"Generator for HTML output.");
// This anchor is used to force the linker to link in the generated object
// file and thus register the generator.
volatile int HTMLGeneratorAnchorSource = 0;
} // namespace doc
} // namespace clang

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

Show All 12 Lines
#include "llvm/Support/Path.h" #include "llvm/Support/Path.h"
#include <string> #include <string>
using namespace llvm; using namespace llvm;
namespace clang { namespace clang {
namespace doc { namespace doc {
// Enum conversion
std::string getAccess(AccessSpecifier AS) {
switch (AS) {
case AccessSpecifier::AS_public:
return "public";
case AccessSpecifier::AS_protected:
return "protected";
case AccessSpecifier::AS_private:
return "private";
case AccessSpecifier::AS_none:
return {};
}
llvm_unreachable("Unknown AccessSpecifier");
}
std::string getTagType(TagTypeKind AS) {
switch (AS) {
case TagTypeKind::TTK_Class:
return "class";
case TagTypeKind::TTK_Union:
return "union";
case TagTypeKind::TTK_Interface:
return "interface";
case TagTypeKind::TTK_Struct:
return "struct";
case TagTypeKind::TTK_Enum:
return "enum";
}
llvm_unreachable("Unknown TagTypeKind");
}
// Markdown generation // Markdown generation
std::string genItalic(const Twine &Text) { return "*" + Text.str() + "*"; } static std::string genItalic(const Twine &Text) { return "*" + Text.str() + "*"; }
std::string genEmphasis(const Twine &Text) { return "**" + Text.str() + "**"; } static std::string genEmphasis(const Twine &Text) { return "**" + Text.str() + "**"; }
std::string genLink(const Twine &Text, const Twine &Link) { static std::string genLink(const Twine &Text, const Twine &Link) {
return "[" + Text.str() + "](" + Link.str() + ")"; return "[" + Text.str() + "](" + Link.str() + ")";
} }
std::string genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs) { static void writeLine(const Twine &Text, raw_ostream &OS) {
juliehockettUnsubmitted
Done
ReplyInline Actions

Can you re-static these?

juliehockett: Can you re-static these?
std::string Buffer; OS << Text << "\n\n";
llvm::raw_string_ostream Stream(Buffer);
bool First = true;
for (const auto &R : Refs) {
if (!First)
Stream << ", ";
Stream << R.Name;
First = false;
}
return Stream.str();
} }
void writeLine(const Twine &Text, raw_ostream &OS) { OS << Text << "\n\n"; } static void writeNewLine(raw_ostream &OS) { OS << "\n\n"; }
void writeNewLine(raw_ostream &OS) { OS << "\n\n"; }
void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) { static void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) {
OS << std::string(Num, '#') + " " + Text << "\n\n"; OS << std::string(Num, '#') + " " + Text << "\n\n";
} }
void writeFileDefinition(const Location &L, raw_ostream &OS) { static void writeFileDefinition(const Location &L, raw_ostream &OS) {
OS << genItalic("Defined at line " + std::to_string(L.LineNumber) + " of " + OS << genItalic("Defined at line " + std::to_string(L.LineNumber) + " of " +
L.Filename) L.Filename)
<< "\n\n"; << "\n\n";
} }
void writeDescription(const CommentInfo &I, raw_ostream &OS) { static void writeDescription(const CommentInfo &I, raw_ostream &OS) {
if (I.Kind == "FullComment") { if (I.Kind == "FullComment") {
for (const auto &Child : I.Children) for (const auto &Child : I.Children)
writeDescription(*Child, OS); writeDescription(*Child, OS);
} else if (I.Kind == "ParagraphComment") { } else if (I.Kind == "ParagraphComment") {
for (const auto &Child : I.Children) for (const auto &Child : I.Children)
writeDescription(*Child, OS); writeDescription(*Child, OS);
writeNewLine(OS); writeNewLine(OS);
} else if (I.Kind == "BlockCommandComment") { } else if (I.Kind == "BlockCommandComment") {
Show All 31 Lines if (I.Kind == "FullComment") {
writeLine("</" + I.Name + ">", OS); writeLine("</" + I.Name + ">", OS);
} else if (I.Kind == "TextComment") { } else if (I.Kind == "TextComment") {
OS << I.Text; OS << I.Text;
} else { } else {
OS << "Unknown comment kind: " << I.Kind << ".\n\n"; OS << "Unknown comment kind: " << I.Kind << ".\n\n";
} }
} }
void genMarkdown(const EnumInfo &I, llvm::raw_ostream &OS) { static void genMarkdown(const EnumInfo &I, llvm::raw_ostream &OS) {
if (I.Scoped) if (I.Scoped)
writeLine("| enum class " + I.Name + " |", OS); writeLine("| enum class " + I.Name + " |", OS);
else else
writeLine("| enum " + I.Name + " |", OS); writeLine("| enum " + I.Name + " |", OS);
writeLine("--", OS); writeLine("--", OS);
std::string Buffer; std::string Buffer;
llvm::raw_string_ostream Members(Buffer); llvm::raw_string_ostream Members(Buffer);
if (!I.Members.empty()) if (!I.Members.empty())
for (const auto &N : I.Members) for (const auto &N : I.Members)
Members << "| " << N << " |\n"; Members << "| " << N << " |\n";
writeLine(Members.str(), OS); writeLine(Members.str(), OS);
if (I.DefLoc) if (I.DefLoc)
writeFileDefinition(I.DefLoc.getValue(), OS); writeFileDefinition(I.DefLoc.getValue(), OS);
for (const auto &C : I.Description) for (const auto &C : I.Description)
writeDescription(C, OS); writeDescription(C, OS);
} }
void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) { static void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) {
std::string Buffer; std::string Buffer;
llvm::raw_string_ostream Stream(Buffer); llvm::raw_string_ostream Stream(Buffer);
bool First = true; bool First = true;
for (const auto &N : I.Params) { for (const auto &N : I.Params) {
if (!First) if (!First)
Stream << ", "; Stream << ", ";
Stream << N.Type.Name + " " + N.Name; Stream << N.Type.Name + " " + N.Name;
First = false; First = false;
Show All 10 Lines writeLine(genItalic(I.ReturnType.Type.Name + " " + I.Name + "(" +
OS); OS);
if (I.DefLoc) if (I.DefLoc)
writeFileDefinition(I.DefLoc.getValue(), OS); writeFileDefinition(I.DefLoc.getValue(), OS);
for (const auto &C : I.Description) for (const auto &C : I.Description)
writeDescription(C, OS); writeDescription(C, OS);
} }
void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) { static void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) {
if (I.Name == "") if (I.Name == "")
writeHeader("Global Namespace", 1, OS); writeHeader("Global Namespace", 1, OS);
else else
writeHeader("namespace " + I.Name, 1, OS); writeHeader("namespace " + I.Name, 1, OS);
writeNewLine(OS); writeNewLine(OS);
if (!I.Description.empty()) { if (!I.Description.empty()) {
for (const auto &C : I.Description) for (const auto &C : I.Description)
Show All 22 Linesstatic void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) {
if (!I.ChildEnums.empty()) { if (!I.ChildEnums.empty()) {
writeHeader("Enums", 2, OS); writeHeader("Enums", 2, OS);
for (const auto &E : I.ChildEnums) for (const auto &E : I.ChildEnums)
genMarkdown(E, OS); genMarkdown(E, OS);
writeNewLine(OS); writeNewLine(OS);
} }
} }
void genMarkdown(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); writeHeader(getTagType(I.TagType) + " " + I.Name, 1, OS);
if (I.DefLoc) if (I.DefLoc)
writeFileDefinition(I.DefLoc.getValue(), OS); writeFileDefinition(I.DefLoc.getValue(), OS);
if (!I.Description.empty()) { if (!I.Description.empty()) {
for (const auto &C : I.Description) for (const auto &C : I.Description)
writeDescription(C, OS); writeDescription(C, OS);
writeNewLine(OS); writeNewLine(OS);
▲ Show 20 Lines • Show All 86 Lines • Show Last 20 Lines

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

Show First 20 Lines • Show All 59 Lines • ▼ Show 20 Lines
static llvm::cl::opt<bool> DoxygenOnly( static llvm::cl::opt<bool> DoxygenOnly(
"doxygen", "doxygen",
llvm::cl::desc("Use only doxygen-style comments to generate docs."), llvm::cl::desc("Use only doxygen-style comments to generate docs."),
llvm::cl::init(false), llvm::cl::cat(ClangDocCategory)); llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
enum OutputFormatTy { enum OutputFormatTy {
md, md,
yaml, yaml,
html,
}; };
static llvm::cl::opt<OutputFormatTy> static llvm::cl::opt<OutputFormatTy>
FormatEnum("format", llvm::cl::desc("Format for outputted docs."), FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml", llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml",
"Documentation in YAML format."), "Documentation in YAML format."),
clEnumValN(OutputFormatTy::md, "md", clEnumValN(OutputFormatTy::md, "md",
"Documentation in MD format.")), "Documentation in MD format."),
clEnumValN(OutputFormatTy::html, "html",
"Documentation in HTML format.")),
llvm::cl::init(OutputFormatTy::yaml), llvm::cl::init(OutputFormatTy::yaml),
llvm::cl::cat(ClangDocCategory)); llvm::cl::cat(ClangDocCategory));
std::string getFormatString() { std::string getFormatString() {
switch (FormatEnum) { switch (FormatEnum) {
case OutputFormatTy::yaml: case OutputFormatTy::yaml:
return "yaml"; return "yaml";
case OutputFormatTy::md: case OutputFormatTy::md:
return "md"; return "md";
case OutputFormatTy::html:
return "html";
} }
llvm_unreachable("Unknown OutputFormatTy"); llvm_unreachable("Unknown OutputFormatTy");
} }
bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) { bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) {
std::error_code OK; std::error_code OK;
llvm::SmallString<128> DocsRootPath; llvm::SmallString<128> DocsRootPath;
if (ClearDirectory) { if (ClearDirectory) {
▲ Show 20 Lines • Show All 148 Lines • Show Last 20 Lines

clang-tools-extra/unittests/clang-doc/CMakeLists.txt

set(LLVM_LINK_COMPONENTS set(LLVM_LINK_COMPONENTS
support support
BitReader BitReader
BitWriter BitWriter
) )
get_filename_component(CLANG_DOC_SOURCE_DIR get_filename_component(CLANG_DOC_SOURCE_DIR
${CMAKE_CURRENT_SOURCE_DIR}/../../clang-doc REALPATH) ${CMAKE_CURRENT_SOURCE_DIR}/../../clang-doc REALPATH)
include_directories( include_directories(
${CLANG_DOC_SOURCE_DIR} ${CLANG_DOC_SOURCE_DIR}
) )
add_extra_unittest(ClangDocTests add_extra_unittest(ClangDocTests
BitcodeTest.cpp BitcodeTest.cpp
ClangDocTest.cpp ClangDocTest.cpp
HTMLGeneratorTest.cpp
MDGeneratorTest.cpp MDGeneratorTest.cpp
MergeTest.cpp MergeTest.cpp
SerializeTest.cpp SerializeTest.cpp
YAMLGeneratorTest.cpp YAMLGeneratorTest.cpp
) )
target_link_libraries(ClangDocTests target_link_libraries(ClangDocTests
PRIVATE PRIVATE
Show All 11 Lines

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

  • This file was added.
//===-- clang-doc/HTMLGeneratorTest.cpp -----------------------------------===//
//
// 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 "ClangDocTest.h"
#include "Generators.h"
#include "Representation.h"
#include "gtest/gtest.h"
namespace clang {
namespace doc {
std::unique_ptr<Generator> getHTMLGenerator() {
auto G = doc::findGeneratorByName("html");
if (!G)
return nullptr;
return std::move(G.get());
}
TEST(HTMLGeneratorTest, emitNamespaceHTML) {
NamespaceInfo I;
I.Name = "Namespace";
I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
I.ChildNamespaces.emplace_back(EmptySID, "ChildNamespace",
InfoType::IT_namespace);
I.ChildRecords.emplace_back(EmptySID, "ChildStruct", InfoType::IT_record);
I.ChildFunctions.emplace_back();
I.ChildFunctions.back().Name = "OneFunction";
I.ChildEnums.emplace_back();
I.ChildEnums.back().Name = "OneEnum";
auto G = getHTMLGenerator();
assert(G);
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/>
<title>namespace Namespace</title>
<div>
<h1>namespace Namespace</h1>
<h2>Namespaces</h2>
<ul>
<li>ChildNamespace</li>
</ul>
<h2>Records</h2>
<ul>
<li>ChildStruct</li>
</ul>
<h2>Functions</h2>
<div>
<h3>OneFunction</h3>
<p>
OneFunction()
</p>
</div>
<h2>Enums</h2>
<div>
<h3>enum OneEnum</h3>
</div>
</div>
)raw";
EXPECT_EQ(Expected, Actual.str());
}
TEST(HTMLGeneratorTest, emitRecordHTML) {
RecordInfo I;
I.Name = "r";
I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
I.Members.emplace_back("int", "X", AccessSpecifier::AS_private);
I.TagType = TagTypeKind::TTK_Class;
I.Parents.emplace_back(EmptySID, "F", InfoType::IT_record);
I.VirtualParents.emplace_back(EmptySID, "G", InfoType::IT_record);
I.ChildRecords.emplace_back(EmptySID, "ChildStruct", InfoType::IT_record);
I.ChildFunctions.emplace_back();
I.ChildFunctions.back().Name = "OneFunction";
I.ChildEnums.emplace_back();
I.ChildEnums.back().Name = "OneEnum";
auto G = getHTMLGenerator();
assert(G);
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/>
<title>class r</title>
<div>
<h1>class r</h1>
<p>
Defined at line 10 of test.cpp
</p>
<p>
Inherits from F, G
</p>
<h2>Members</h2>
<ul>
<li>private int X</li>
</ul>
<h2>Records</h2>
<ul>
<li>ChildStruct</li>
</ul>
<h2>Functions</h2>
<div>
<h3>OneFunction</h3>
<p>
OneFunction()
</p>
</div>
<h2>Enums</h2>
<div>
<h3>enum OneEnum</h3>
</div>
</div>
)raw";
EXPECT_EQ(Expected, Actual.str());
}
TEST(HTMLGeneratorTest, emitFunctionHTML) {
FunctionInfo I;
I.Name = "f";
I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
I.ReturnType = TypeInfo(EmptySID, "void", InfoType::IT_default);
I.Params.emplace_back("int", "P");
I.IsMethod = true;
I.Parent = Reference(EmptySID, "Parent", InfoType::IT_record);
auto G = getHTMLGenerator();
assert(G);
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/>
<title></title>
<div>
<h3>f</h3>
<p>
void f(int P)
</p>
<p>
Defined at line 10 of test.cpp
</p>
</div>
)raw";
EXPECT_EQ(Expected, Actual.str());
}
TEST(HTMLGeneratorTest, emitEnumHTML) {
EnumInfo I;
I.Name = "e";
I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
I.Members.emplace_back("X");
I.Scoped = true;
auto G = getHTMLGenerator();
assert(G);
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/>
<title></title>
<div>
<h3>enum class e</h3>
<ul>
<li>X</li>
</ul>
<p>
Defined at line 10 of test.cpp
</p>
</div>
)raw";
EXPECT_EQ(Expected, Actual.str());
}
TEST(HTMLGeneratorTest, emitCommentHTML) {
FunctionInfo I;
I.Name = "f";
I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
I.ReturnType = TypeInfo(EmptySID, "void", InfoType::IT_default);
I.Params.emplace_back("int", "I");
I.Params.emplace_back("int", "J");
CommentInfo Top;
Top.Kind = "FullComment";
Top.Children.emplace_back(llvm::make_unique<CommentInfo>());
CommentInfo *BlankLine = Top.Children.back().get();
BlankLine->Kind = "ParagraphComment";
BlankLine->Children.emplace_back(llvm::make_unique<CommentInfo>());
BlankLine->Children.back()->Kind = "TextComment";
Top.Children.emplace_back(llvm::make_unique<CommentInfo>());
CommentInfo *Brief = Top.Children.back().get();
Brief->Kind = "ParagraphComment";
Brief->Children.emplace_back(llvm::make_unique<CommentInfo>());
Brief->Children.back()->Kind = "TextComment";
Brief->Children.back()->Name = "ParagraphComment";
Brief->Children.back()->Text = " Brief description.";
Top.Children.emplace_back(llvm::make_unique<CommentInfo>());
CommentInfo *Extended = Top.Children.back().get();
Extended->Kind = "ParagraphComment";
Extended->Children.emplace_back(llvm::make_unique<CommentInfo>());
Extended->Children.back()->Kind = "TextComment";
Extended->Children.back()->Text = " Extended description that";
Extended->Children.emplace_back(llvm::make_unique<CommentInfo>());
Extended->Children.back()->Kind = "TextComment";
Extended->Children.back()->Text = " continues onto the next line.";
I.Description.emplace_back(std::move(Top));
auto G = getHTMLGenerator();
assert(G);
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/>
<title></title>
<div>
<h3>f</h3>
<p>
void f(int I, int J)
</p>
<p>
Defined at line 10 of test.cpp
</p>
<div>
<div>
<p>
Brief description.
</p>
<p>
Extended description that
continues onto the next line.
</p>
</div>
</div>
</div>
)raw";
EXPECT_EQ(Expected, Actual.str());
}
} // namespace doc
} // namespace clang