This is an archive of the discontinued LLVM Phabricator instance.

Differential D65005

[clang-doc] Fix output format of html
ClosedPublic

Authored by DiegoAstiazaran on Jul 19 2019, 11:16 AM.

Details

Reviewers
juliehockett
jakehehrlich
lebedev.ri
Commits
rG64ca85700452: [clang-doc] Fix output format of html
rL367050: [clang-doc] Fix output format of html
rCTE367050: [clang-doc] Fix output format of html
Summary

The children of a TagNode are rendered in the same line as the parent only if they are all TextNodes.
When children are not inline; two text nodes that are adjacent won't have a new line between them, each tag node is rendered in its own line.

Diff Detail

Event Timeline

DiegoAstiazaran created this revision.Jul 19 2019, 11:16 AM
juliehockett accepted this revision.Jul 23 2019, 3:02 PM
This revision is now accepted and ready to land.Jul 23 2019, 3:02 PM
DiegoAstiazaran updated this revision to Diff 211812.Jul 25 2019, 1:45 PM
Closed by commit rL367050: [clang-doc] Fix output format of html (authored by DiegoAstiazaran). · Explain WhyJul 25 2019, 1:51 PM
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptJul 25 2019, 1:51 PM
Herald added a subscriber: llvm-commits. · View Herald Transcript
DiegoAstiazaran mentioned this in D65003: [clang-doc] Add index in each info html file.Jul 25 2019, 6:59 PM
DiegoAstiazaran mentioned this in D65030: [clang-doc] Add second index for sections within info's content.Jul 26 2019, 10:50 AM

Revision Contents

PathSize
clang-tools-extra/
clang-doc/
54 lines
unittests/
clang-doc/
48 lines

Diff 211812

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

Show All 38 Linespublic:
HTMLTag() = default; HTMLTag() = default;
constexpr HTMLTag(TagType Value) : Value(Value) {} constexpr HTMLTag(TagType Value) : Value(Value) {}
operator TagType() const { return Value; } operator TagType() const { return Value; }
operator bool() = delete; operator bool() = delete;
bool IsSelfClosing() const; bool IsSelfClosing() const;
bool HasInlineChildren() const;
llvm::SmallString<16> ToString() const; llvm::SmallString<16> ToString() const;
private: private:
TagType Value; TagType Value;
}; };
enum NodeType { enum NodeType {
NODE_TEXT, NODE_TEXT,
NODE_TAG, NODE_TAG,
}; };
struct HTMLNode { struct HTMLNode {
HTMLNode(NodeType Type) : Type(Type) {} HTMLNode(NodeType Type) : Type(Type) {}
virtual ~HTMLNode() = default; virtual ~HTMLNode() = default;
virtual void Render(llvm::raw_ostream &OS, int IndentationLevel) = 0; virtual void Render(llvm::raw_ostream &OS, int IndentationLevel) = 0;
NodeType Type; // Type of node NodeType Type; // Type of node
}; };
struct TextNode : public HTMLNode { struct TextNode : public HTMLNode {
TextNode(const Twine &Text, bool Indented = true) TextNode(const Twine &Text)
: HTMLNode(NodeType::NODE_TEXT), Text(Text.str()), Indented(Indented) {} : HTMLNode(NodeType::NODE_TEXT), Text(Text.str()) {}
std::string Text; // Content of node 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; void Render(llvm::raw_ostream &OS, int IndentationLevel) override;
}; };
struct TagNode : public HTMLNode { struct TagNode : public HTMLNode {
TagNode(HTMLTag Tag) TagNode(HTMLTag Tag) : HTMLNode(NodeType::NODE_TAG), Tag(Tag) {}
: HTMLNode(NodeType::NODE_TAG), Tag(Tag),
InlineChildren(Tag.HasInlineChildren()),
SelfClosing(Tag.IsSelfClosing()) {}
TagNode(HTMLTag Tag, const Twine &Text) : TagNode(Tag) { TagNode(HTMLTag Tag, const Twine &Text) : TagNode(Tag) {
Children.emplace_back( Children.emplace_back(llvm::make_unique<TextNode>(Text.str()));
llvm::make_unique<TextNode>(Text.str(), !InlineChildren));
} }
HTMLTag Tag; // Name of HTML Tag (p, div, h1) 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 std::vector<std::unique_ptr<HTMLNode>> Children; // List of child nodes
llvm::StringMap<llvm::SmallString<16>> llvm::StringMap<llvm::SmallString<16>>
Attributes; // List of key-value attributes for tag Attributes; // List of key-value attributes for tag
void Render(llvm::raw_ostream &OS, int IndentationLevel) override; void Render(llvm::raw_ostream &OS, int IndentationLevel) override;
}; };
constexpr const char *kDoctypeDecl = "<!DOCTYPE html>"; constexpr const char *kDoctypeDecl = "<!DOCTYPE html>";
Show All 24 Linesbool HTMLTag::IsSelfClosing() const {
case HTMLTag::TAG_UL: case HTMLTag::TAG_UL:
case HTMLTag::TAG_LI: case HTMLTag::TAG_LI:
case HTMLTag::TAG_A: case HTMLTag::TAG_A:
return false; return false;
} }
llvm_unreachable("Unhandled HTMLTag::TagType"); llvm_unreachable("Unhandled HTMLTag::TagType");
} }
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:
case HTMLTag::TAG_A:
return true;
case HTMLTag::TAG_DIV:
case HTMLTag::TAG_P:
case HTMLTag::TAG_UL:
return false;
}
llvm_unreachable("Unhandled HTMLTag::TagType");
}
llvm::SmallString<16> HTMLTag::ToString() const { llvm::SmallString<16> HTMLTag::ToString() const {
switch (Value) { switch (Value) {
case HTMLTag::TAG_META: case HTMLTag::TAG_META:
return llvm::SmallString<16>("meta"); return llvm::SmallString<16>("meta");
case HTMLTag::TAG_TITLE: case HTMLTag::TAG_TITLE:
return llvm::SmallString<16>("title"); return llvm::SmallString<16>("title");
case HTMLTag::TAG_DIV: case HTMLTag::TAG_DIV:
return llvm::SmallString<16>("div"); return llvm::SmallString<16>("div");
Show All 11 Lines case HTMLTag::TAG_LI:
return llvm::SmallString<16>("li"); return llvm::SmallString<16>("li");
case HTMLTag::TAG_A: case HTMLTag::TAG_A:
return llvm::SmallString<16>("a"); return llvm::SmallString<16>("a");
} }
llvm_unreachable("Unhandled HTMLTag::TagType"); llvm_unreachable("Unhandled HTMLTag::TagType");
} }
void TextNode::Render(llvm::raw_ostream &OS, int IndentationLevel) { void TextNode::Render(llvm::raw_ostream &OS, int IndentationLevel) {
if (Indented)
OS.indent(IndentationLevel * 2); OS.indent(IndentationLevel * 2);
printHTMLEscaped(Text, OS); printHTMLEscaped(Text, OS);
} }
void TagNode::Render(llvm::raw_ostream &OS, int IndentationLevel) { void TagNode::Render(llvm::raw_ostream &OS, int IndentationLevel) {
// Children nodes are rendered in the same line if all of them are text nodes
bool InlineChildren = true;
for (const auto &C : Children)
if (C->Type == NodeType::NODE_TAG) {
InlineChildren = false;
break;
}
OS.indent(IndentationLevel * 2); OS.indent(IndentationLevel * 2);
OS << "<" << Tag.ToString(); OS << "<" << Tag.ToString();
for (const auto &A : Attributes) for (const auto &A : Attributes)
OS << " " << A.getKey() << "=\"" << A.getValue() << "\""; OS << " " << A.getKey() << "=\"" << A.getValue() << "\"";
if (SelfClosing) { if (Tag.IsSelfClosing()) {
OS << "/>"; OS << "/>";
return; return;
} }
OS << ">"; OS << ">";
if (!InlineChildren) if (!InlineChildren)
OS << "\n"; OS << "\n";
bool NewLineRendered = true; bool NewLineRendered = true;
for (const auto &C : Children) { for (const auto &C : Children) {
▲ Show 20 Lines • Show All 183 Lines • ▼ Show 20 Lines for (const auto &Child : I.Children) {
ParagraphComment->Children.emplace_back(std::move(Node)); ParagraphComment->Children.emplace_back(std::move(Node));
} }
if (ParagraphComment->Children.empty()) if (ParagraphComment->Children.empty())
return nullptr; return nullptr;
return std::move(ParagraphComment); return std::move(ParagraphComment);
} else if (I.Kind == "TextComment") { } else if (I.Kind == "TextComment") {
if (I.Text == "") if (I.Text == "")
return nullptr; return nullptr;
return llvm::make_unique<TextNode>(I.Text, true); return llvm::make_unique<TextNode>(I.Text);
} }
return nullptr; return nullptr;
} }
static std::unique_ptr<TagNode> genHTML(const std::vector<CommentInfo> &C) { static std::unique_ptr<TagNode> genHTML(const std::vector<CommentInfo> &C) {
auto CommentBlock = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV); auto CommentBlock = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
for (const auto &Child : C) { for (const auto &Child : C) {
if (std::unique_ptr<HTMLNode> Node = genHTML(Child)) if (std::unique_ptr<HTMLNode> Node = genHTML(Child))
▲ Show 20 Lines • Show All 217 Lines • Show Last 20 Lines

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

Show First 20 Lines • Show All 50 Lines • ▼ Show 20 Lines<div>
</ul> </ul>
<h2>Records</h2> <h2>Records</h2>
<ul> <ul>
<li>ChildStruct</li> <li>ChildStruct</li>
</ul> </ul>
<h2>Functions</h2> <h2>Functions</h2>
<div> <div>
<h3>OneFunction</h3> <h3>OneFunction</h3>
<p> <p>OneFunction()</p>
OneFunction()
</p>
</div> </div>
<h2>Enums</h2> <h2>Enums</h2>
<div> <div>
<h3>enum OneEnum</h3> <h3>enum OneEnum</h3>
</div> </div>
</div> </div>
)raw"; )raw";
Show All 32 LinesTEST(HTMLGeneratorTest, emitRecordHTML) {
llvm::sys::path::native("../../../path/to/F.html", PathToF); llvm::sys::path::native("../../../path/to/F.html", PathToF);
SmallString<16> PathToInt; SmallString<16> PathToInt;
llvm::sys::path::native("../int.html", PathToInt); llvm::sys::path::native("../int.html", PathToInt);
std::string Expected = R"raw(<!DOCTYPE html> std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/> <meta charset="utf-8"/>
<title>class r</title> <title>class r</title>
<div> <div>
<h1>class r</h1> <h1>class r</h1>
<p> <p>Defined at line 10 of test.cpp</p>
Defined at line 10 of test.cpp
</p>
<p> <p>
Inherits from Inherits from
<a href=")raw" + std::string(PathToF.str()) + <a href=")raw" + std::string(PathToF.str()) +
R"raw(">F</a> R"raw(">F</a>
, G , G
</p> </p>
<h2>Members</h2> <h2>Members</h2>
<ul> <ul>
<li>private <a href=")raw" + <li>
std::string(PathToInt.str()) + R"raw(">int</a> X</li> private
<a href=")raw" + std::string(PathToInt.str()) +
R"raw(">int</a>
X
</li>
</ul> </ul>
<h2>Records</h2> <h2>Records</h2>
<ul> <ul>
<li>ChildStruct</li> <li>ChildStruct</li>
</ul> </ul>
<h2>Functions</h2> <h2>Functions</h2>
<div> <div>
<h3>OneFunction</h3> <h3>OneFunction</h3>
<p> <p>OneFunction()</p>
OneFunction()
</p>
</div> </div>
<h2>Enums</h2> <h2>Enums</h2>
<div> <div>
<h3>enum OneEnum</h3> <h3>enum OneEnum</h3>
</div> </div>
</div> </div>
)raw"; )raw";
Show All 33 Lines<div>
<p> <p>
<a href=")raw" + std::string(PathToFloat.str()) + <a href=")raw" + std::string(PathToFloat.str()) +
R"raw(">float</a> R"raw(">float</a>
f( f(
<a href=")raw" + std::string(PathToInt.str()) + <a href=")raw" + std::string(PathToInt.str()) +
R"raw(">int</a> R"raw(">int</a>
P) P)
</p> </p>
<p> <p>Defined at line 10 of test.cpp</p>
Defined at line 10 of test.cpp
</p>
</div> </div>
)raw"; )raw";
EXPECT_EQ(Expected, Actual.str()); EXPECT_EQ(Expected, Actual.str());
} }
TEST(HTMLGeneratorTest, emitEnumHTML) { TEST(HTMLGeneratorTest, emitEnumHTML) {
EnumInfo I; EnumInfo I;
Show All 15 LinesTEST(HTMLGeneratorTest, emitEnumHTML) {
std::string Expected = R"raw(<!DOCTYPE html> std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/> <meta charset="utf-8"/>
<title></title> <title></title>
<div> <div>
<h3>enum class e</h3> <h3>enum class e</h3>
<ul> <ul>
<li>X</li> <li>X</li>
</ul> </ul>
<p> <p>Defined at line 10 of test.cpp</p>
Defined at line 10 of test.cpp
</p>
</div> </div>
)raw"; )raw";
EXPECT_EQ(Expected, Actual.str()); EXPECT_EQ(Expected, Actual.str());
} }
TEST(HTMLGeneratorTest, emitCommentHTML) { TEST(HTMLGeneratorTest, emitCommentHTML) {
FunctionInfo I; FunctionInfo I;
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 LinesTEST(HTMLGeneratorTest, emitCommentHTML) {
llvm::raw_string_ostream Actual(Buffer); llvm::raw_string_ostream Actual(Buffer);
auto Err = G->generateDocForInfo(&I, Actual); auto Err = G->generateDocForInfo(&I, Actual);
assert(!Err); assert(!Err);
std::string Expected = R"raw(<!DOCTYPE html> std::string Expected = R"raw(<!DOCTYPE html>
<meta charset="utf-8"/> <meta charset="utf-8"/>
<title></title> <title></title>
<div> <div>
<h3>f</h3> <h3>f</h3>
<p> <p>void f(int I, int J)</p>
void f(int I, int J) <p>Defined at line 10 of test.cpp</p>
</p>
<p>
Defined at line 10 of test.cpp
</p>
<div> <div>
<div> <div>
<p> <p> Brief description.</p>
Brief description. <p> Extended description that continues onto the next line.</p>
</p> <p> Comment with html entities: &amp;, &lt;, &gt;, &quot;, &apos;.</p>
<p>
Extended description that continues onto the next line.
</p>
<p>
Comment with html entities: &amp;, &lt;, &gt;, &quot;, &apos;.
</p>
</div> </div>
</div> </div>
</div> </div>
)raw"; )raw";
EXPECT_EQ(Expected, Actual.str()); EXPECT_EQ(Expected, Actual.str());
} }
} // namespace doc } // namespace doc
} // namespace clang } // namespace clang