Skip to content

Commit e02e9b6

Browse files
coryancoryan
authored
impl(docfx): generate syntax element for classes (#11132)
1 parent c9b91ec commit e02e9b6

3 files changed

Lines changed: 175 additions & 9 deletions

File tree

‎docfx/doxygen2syntax.cc‎

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,12 @@ namespace docfx {
2020
namespace {
2121

2222
void AppendLocation(YAML::Emitter& yaml, YamlContext const& ctx,
23-
pugi::xml_node const& node, char const* file_attribute,
24-
char const* line_attribute) {
25-
auto const name = std::string_view{node.child("name").child_value()};
23+
pugi::xml_node const& node, char const* name_attribute) {
24+
auto const name = std::string_view{node.child(name_attribute).child_value()};
2625
auto const location = node.child("location");
2726
if (name.empty() || !location) return;
28-
auto const line =
29-
std::string_view{location.attribute(line_attribute).as_string()};
30-
auto const file = std::string{location.attribute(file_attribute).as_string()};
27+
auto const line = std::string_view{location.attribute("line").as_string()};
28+
auto const file = std::string{location.attribute("file").as_string()};
3129
if (line.empty() || file.empty()) return;
3230

3331
auto const repo =
@@ -139,13 +137,20 @@ std::string FunctionSyntaxContent(pugi::xml_node const& node) {
139137
return std::move(os).str();
140138
}
141139

140+
std::string ClassSyntaxContent(pugi::xml_node const& node) {
141+
std::ostringstream os;
142+
os << "// Found in #include <" << node.child_value("includes") << ">\n"
143+
<< "class " << node.child_value("compoundname") << " { ... };";
144+
return std::move(os).str();
145+
}
146+
142147
void AppendEnumSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
143148
pugi::xml_node const& node) {
144149
yaml << YAML::Key << "syntax" << YAML::Value //
145150
<< YAML::BeginMap //
146151
<< YAML::Key << "contents" << YAML::Value << YAML::Literal //
147152
<< EnumSyntaxContent(node);
148-
AppendLocation(yaml, ctx, node, "file", "line");
153+
AppendLocation(yaml, ctx, node, "name");
149154
yaml << YAML::EndMap;
150155
}
151156

@@ -155,7 +160,7 @@ void AppendTypedefSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
155160
<< YAML::BeginMap //
156161
<< YAML::Key << "contents" << YAML::Value << YAML::Literal //
157162
<< TypedefSyntaxContent(node);
158-
AppendLocation(yaml, ctx, node, "file", "line");
163+
AppendLocation(yaml, ctx, node, "name");
159164
yaml << YAML::EndMap;
160165
}
161166

@@ -184,7 +189,18 @@ void AppendFunctionSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
184189
}
185190
yaml << YAML::EndSeq;
186191
}
187-
AppendLocation(yaml, ctx, node, "file", "line");
192+
AppendLocation(yaml, ctx, node, "name");
193+
yaml << YAML::EndMap;
194+
}
195+
196+
// Generate the `syntax` element for a class.
197+
void AppendClassSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
198+
pugi::xml_node const& node) {
199+
yaml << YAML::Key << "syntax" << YAML::Value //
200+
<< YAML::BeginMap //
201+
<< YAML::Key << "contents" << YAML::Value << YAML::Literal //
202+
<< ClassSyntaxContent(node);
203+
AppendLocation(yaml, ctx, node, "compoundname");
188204
yaml << YAML::EndMap;
189205
}
190206

‎docfx/doxygen2syntax.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,9 @@ std::string TypedefSyntaxContent(pugi::xml_node const& node);
4141
// Generate the `syntax.content` element for a function.
4242
std::string FunctionSyntaxContent(pugi::xml_node const& node);
4343

44+
// Generate the `syntax.content` element for a class.
45+
std::string ClassSyntaxContent(pugi::xml_node const& node);
46+
4447
// Generate the `syntax` element for an enum.
4548
void AppendEnumSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
4649
pugi::xml_node const& node);
@@ -53,6 +56,10 @@ void AppendTypedefSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
5356
void AppendFunctionSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
5457
pugi::xml_node const& node);
5558

59+
// Generate the `syntax` element for a class.
60+
void AppendClassSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
61+
pugi::xml_node const& node);
62+
5663
} // namespace docfx
5764

5865
#endif // GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2SYNTAX_H

‎docfx/doxygen2syntax_test.cc‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,108 @@ auto constexpr kFunctionXml = R"xml(<?xml version="1.0" standalone="yes"?>
134134
</memberdef>
135135
</doxygen>)xml";
136136

137+
auto constexpr kClassXml = R"xml(xml(<?xml version="1.0" standalone="yes"?>
138+
<doxygen version="1.9.1" xml:lang="en-US">
139+
<compounddef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="classgoogle_1_1cloud_1_1RuntimeStatusError" kind="class" language="C++" prot="public">
140+
<compoundname>google::cloud::RuntimeStatusError</compoundname>
141+
<basecompoundref prot="public" virt="non-virtual">std::runtime_error</basecompoundref>
142+
<includes refid="status_8h" local="no">google/cloud/status.h</includes>
143+
<sectiondef kind="private-attrib">
144+
<memberdef kind="variable" id="classgoogle_1_1cloud_1_1RuntimeStatusError_1a85bebd1a98468aff6b7f5fe54f7b4241" prot="private" static="no" mutable="no">
145+
<type><ref refid="classgoogle_1_1cloud_1_1Status" kindref="compound">Status</ref></type>
146+
<definition>Status google::cloud::RuntimeStatusError::status_</definition>
147+
<argsstring/>
148+
<name>status_</name>
149+
<qualifiedname>google::cloud::RuntimeStatusError::status_</qualifiedname>
150+
<briefdescription>
151+
</briefdescription>
152+
<detaileddescription>
153+
</detaileddescription>
154+
<inbodydescription>
155+
</inbodydescription>
156+
<location file="status.h" line="168" column="10" bodyfile="status.h" bodystart="168" bodyend="-1"/>
157+
</memberdef>
158+
</sectiondef>
159+
<sectiondef kind="public-func">
160+
<memberdef kind="function" id="classgoogle_1_1cloud_1_1RuntimeStatusError_1aac6b78160cce6468696ce77eb1276a95" prot="public" static="no" const="no" explicit="yes" inline="no" virt="non-virtual">
161+
<type/>
162+
<definition>google::cloud::RuntimeStatusError::RuntimeStatusError</definition>
163+
<argsstring>(Status status)</argsstring>
164+
<name>RuntimeStatusError</name>
165+
<qualifiedname>google::cloud::RuntimeStatusError::RuntimeStatusError</qualifiedname>
166+
<param>
167+
<type><ref refid="classgoogle_1_1cloud_1_1Status" kindref="compound">Status</ref></type>
168+
<declname>status</declname>
169+
</param>
170+
<briefdescription>
171+
</briefdescription>
172+
<detaileddescription>
173+
</detaileddescription>
174+
<inbodydescription>
175+
</inbodydescription>
176+
<location file="status.h" line="163" column="12"/>
177+
</memberdef>
178+
<memberdef kind="function" id="classgoogle_1_1cloud_1_1RuntimeStatusError_1ac30dbdb272a62aee4eb8f9bf45966c7e" prot="public" static="no" const="yes" explicit="no" inline="yes" virt="non-virtual">
179+
<type><ref refid="classgoogle_1_1cloud_1_1Status" kindref="compound">Status</ref> const &amp;</type>
180+
<definition>Status const &amp; google::cloud::RuntimeStatusError::status</definition>
181+
<argsstring>() const</argsstring>
182+
<name>status</name>
183+
<qualifiedname>google::cloud::RuntimeStatusError::status</qualifiedname>
184+
<briefdescription>
185+
</briefdescription>
186+
<detaileddescription>
187+
</detaileddescription>
188+
<inbodydescription>
189+
</inbodydescription>
190+
<location file="status.h" line="165" column="16" bodyfile="status.h" bodystart="165" bodyend="165"/>
191+
</memberdef>
192+
</sectiondef>
193+
<briefdescription>
194+
<para>A runtime error that wraps a <computeroutput><ref refid="classgoogle_1_1cloud_1_1Status" kindref="compound">google::cloud::Status</ref></computeroutput>. </para>
195+
</briefdescription>
196+
<detaileddescription>
197+
</detaileddescription>
198+
<inheritancegraph>
199+
<node id="1">
200+
<label>google::cloud::RuntimeStatusError</label>
201+
<link refid="classgoogle_1_1cloud_1_1RuntimeStatusError"/>
202+
<childnode refid="2" relation="public-inheritance">
203+
</childnode>
204+
</node>
205+
<node id="3">
206+
<label>std::exception</label>
207+
</node>
208+
<node id="2">
209+
<label>std::runtime_error</label>
210+
<childnode refid="3" relation="public-inheritance">
211+
</childnode>
212+
</node>
213+
</inheritancegraph>
214+
<collaborationgraph>
215+
<node id="1">
216+
<label>google::cloud::RuntimeStatusError</label>
217+
<link refid="classgoogle_1_1cloud_1_1RuntimeStatusError"/>
218+
<childnode refid="2" relation="public-inheritance">
219+
</childnode>
220+
</node>
221+
<node id="3">
222+
<label>std::exception</label>
223+
</node>
224+
<node id="2">
225+
<label>std::runtime_error</label>
226+
<childnode refid="3" relation="public-inheritance">
227+
</childnode>
228+
</node>
229+
</collaborationgraph>
230+
<location file="status.h" line="161" column="1" bodyfile="status.h" bodystart="161" bodyend="169"/>
231+
<listofallmembers>
232+
<member refid="classgoogle_1_1cloud_1_1RuntimeStatusError_1aac6b78160cce6468696ce77eb1276a95" prot="public" virt="non-virtual"><scope>google::cloud::RuntimeStatusError</scope><name>RuntimeStatusError</name></member>
233+
<member refid="classgoogle_1_1cloud_1_1RuntimeStatusError_1ac30dbdb272a62aee4eb8f9bf45966c7e" prot="public" virt="non-virtual"><scope>google::cloud::RuntimeStatusError</scope><name>status</name></member>
234+
<member refid="classgoogle_1_1cloud_1_1RuntimeStatusError_1a85bebd1a98468aff6b7f5fe54f7b4241" prot="private" virt="non-virtual"><scope>google::cloud::RuntimeStatusError</scope><name>status_</name></member>
235+
</listofallmembers>
236+
</compounddef>
237+
</doxygen>)xml";
238+
137239
TEST(Doxygen2SyntaxContent, Enum) {
138240
auto constexpr kExpected = R"""(enum class google::cloud::Idempotency {
139241
kIdempotent,
@@ -186,6 +288,19 @@ google::cloud::CompletionQueue::MakeRelativeTimer (
186288
EXPECT_EQ(actual, kExpected);
187289
}
188290

291+
TEST(Doxygen2SyntaxContent, Class) {
292+
auto constexpr kExpected =
293+
R"""(// Found in #include <google/cloud/status.h>
294+
class google::cloud::RuntimeStatusError { ... };)""";
295+
pugi::xml_document doc;
296+
doc.load_string(kClassXml);
297+
auto selected =
298+
doc.select_node("//*[@id='classgoogle_1_1cloud_1_1RuntimeStatusError']");
299+
ASSERT_TRUE(selected);
300+
auto const actual = ClassSyntaxContent(selected.node());
301+
EXPECT_EQ(actual, kExpected);
302+
}
303+
189304
TEST(Doxygen2Syntax, Enum) {
190305
auto constexpr kExpected = R"yml(syntax:
191306
contents: |
@@ -293,5 +408,33 @@ TEST(Doxygen2Syntax, Function) {
293408
EXPECT_EQ(actual, kExpected);
294409
}
295410

411+
TEST(Doxygen2Syntax, Class) {
412+
auto constexpr kExpected = R"yml(syntax:
413+
contents: |
414+
// Found in #include <google/cloud/status.h>
415+
class google::cloud::RuntimeStatusError { ... };
416+
source:
417+
id: google::cloud::RuntimeStatusError
418+
path: google/cloud/status.h
419+
startLine: 161
420+
remote:
421+
repo: https://github.com/googleapis/google-cloud-cpp/
422+
branch: main
423+
path: google/cloud/status.h)yml";
424+
pugi::xml_document doc;
425+
doc.load_string(kClassXml);
426+
auto selected =
427+
doc.select_node("//*[@id='classgoogle_1_1cloud_1_1RuntimeStatusError']");
428+
ASSERT_TRUE(selected);
429+
YamlContext ctx;
430+
ctx.parent_id = "test-only-parent-id";
431+
YAML::Emitter yaml;
432+
yaml << YAML::BeginMap;
433+
AppendClassSyntax(yaml, ctx, selected.node());
434+
yaml << YAML::EndMap;
435+
auto const actual = std::string{yaml.c_str()};
436+
EXPECT_EQ(actual, kExpected);
437+
}
438+
296439
} // namespace
297440
} // namespace docfx

0 commit comments

Comments
 (0)