Skip to content

Commit 92b5d15

Browse files
coryancoryan
authored
impl(docfx): generate YAML for variables (#11178)
1 parent 5b9bae9 commit 92b5d15

3 files changed

Lines changed: 213 additions & 0 deletions

File tree

‎docfx/doxygen2yaml.cc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,31 @@ bool AppendIfTypedef(YAML::Emitter& yaml, YamlContext const& ctx,
188188
return true;
189189
}
190190

191+
bool AppendIfVariable(YAML::Emitter& yaml, YamlContext const& ctx,
192+
pugi::xml_node const& node) {
193+
if (kind(node) != "variable") return false;
194+
auto const id = std::string_view{node.attribute("id").as_string()};
195+
auto const name = std::string_view{node.child("name").child_value()};
196+
auto const qualified_name =
197+
std::string_view{node.child("qualifiedname").child_value()};
198+
yaml << YAML::BeginMap //
199+
<< YAML::Key << "uid" << YAML::Value << id //
200+
<< YAML::Key << "name" << YAML::Value << YAML::Literal << name //
201+
<< YAML::Key << "fullName" //
202+
<< YAML::Value << YAML::Literal << qualified_name //
203+
<< YAML::Key << "id" << YAML::Value << id //
204+
<< YAML::Key << "parent" << YAML::Value << ctx.parent_id //
205+
<< YAML::Key << "type" << YAML::Value << "variable" //
206+
<< YAML::Key << "langs" << YAML::BeginSeq << "cpp" << YAML::EndSeq; //
207+
AppendVariableSyntax(yaml, ctx, node);
208+
auto const summary = Summary(node);
209+
if (!summary.empty()) {
210+
yaml << YAML::Key << "summary" << YAML::Value << YAML::Literal << summary;
211+
}
212+
yaml << YAML::EndMap;
213+
return true;
214+
}
215+
191216
bool AppendIfFunction(YAML::Emitter& yaml, YamlContext const& ctx,
192217
pugi::xml_node const& node) {
193218
if (kind(node) != "function") return false;

‎docfx/doxygen2yaml.h‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,10 @@ bool AppendIfEnum(YAML::Emitter& yaml, YamlContext const& ctx,
4848
bool AppendIfTypedef(YAML::Emitter& yaml, YamlContext const& ctx,
4949
pugi::xml_node const& node);
5050

51+
// Create a YAML entry for a variable definition.
52+
bool AppendIfVariable(YAML::Emitter& yaml, YamlContext const& ctx,
53+
pugi::xml_node const& node);
54+
5155
// Create a YAML entry for a function declaration.
5256
bool AppendIfFunction(YAML::Emitter& yaml, YamlContext const& ctx,
5357
pugi::xml_node const& node);

‎docfx/doxygen2yaml_test.cc‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,148 @@ auto constexpr kStructXml = R"xml(xml(<?xml version="1.0" standalone="yes"?>
171171
</compounddef>
172172
</doxygen>)xml";
173173

174+
auto constexpr kStruct2Xml = R"xml(xml(<?xml version="1.0" standalone="yes"?>
175+
<doxygen>
176+
<compounddef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="structgoogle_1_1cloud_1_1LogRecord" kind="struct" language="C++" prot="public">
177+
<compoundname>google::cloud::LogRecord</compoundname>
178+
<includes refid="log_8h" local="no">google/cloud/log.h</includes>
179+
<sectiondef kind="public-attrib">
180+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a830f8xx5fe86e1581dddbbb2cd922cbc" prot="public" static="no" mutable="no">
181+
<type><ref refid="namespacegoogle_1_1cloud_1aeeb9b9a1eeb3fc7f6ff13bd078172922" kindref="member">Severity</ref></type>
182+
<definition>Severity google::cloud::LogRecord::severity</definition>
183+
<argsstring/>
184+
<name>severity</name>
185+
<qualifiedname>google::cloud::LogRecord::severity</qualifiedname>
186+
<briefdescription>
187+
</briefdescription>
188+
<detaileddescription>
189+
</detaileddescription>
190+
<inbodydescription>
191+
</inbodydescription>
192+
<location file="log.h" line="152" column="12" bodyfile="log.h" bodystart="152" bodyend="-1"/>
193+
</memberdef>
194+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a8a04caf649e69b55404abf2d3b72d4a6" prot="public" static="no" mutable="no">
195+
<type>std::string</type>
196+
<definition>std::string google::cloud::LogRecord::function</definition>
197+
<argsstring/>
198+
<name>function</name>
199+
<qualifiedname>google::cloud::LogRecord::function</qualifiedname>
200+
<briefdescription>
201+
</briefdescription>
202+
<detaileddescription>
203+
</detaileddescription>
204+
<inbodydescription>
205+
</inbodydescription>
206+
<location file="log.h" line="153" column="15" bodyfile="log.h" bodystart="153" bodyend="-1"/>
207+
</memberdef>
208+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a46bc9a3adab542be80be9671d2ff82e6" prot="public" static="no" mutable="no">
209+
<type>std::string</type>
210+
<definition>std::string google::cloud::LogRecord::filename</definition>
211+
<argsstring/>
212+
<name>filename</name>
213+
<qualifiedname>google::cloud::LogRecord::filename</qualifiedname>
214+
<briefdescription>
215+
</briefdescription>
216+
<detaileddescription>
217+
</detaileddescription>
218+
<inbodydescription>
219+
</inbodydescription>
220+
<location file="log.h" line="154" column="15" bodyfile="log.h" bodystart="154" bodyend="-1"/>
221+
</memberdef>
222+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a29f2cf2bafa97addc548c26xx48a4fe0" prot="public" static="no" mutable="no">
223+
<type>int</type>
224+
<definition>int google::cloud::LogRecord::lineno</definition>
225+
<argsstring/>
226+
<name>lineno</name>
227+
<qualifiedname>google::cloud::LogRecord::lineno</qualifiedname>
228+
<briefdescription>
229+
</briefdescription>
230+
<detaileddescription>
231+
</detaileddescription>
232+
<inbodydescription>
233+
</inbodydescription>
234+
<location file="log.h" line="155" column="7" bodyfile="log.h" bodystart="155" bodyend="-1"/>
235+
</memberdef>
236+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a9acea199684809e231263a486559f834" prot="public" static="no" mutable="no">
237+
<type>std::thread::id</type>
238+
<definition>std::thread::id google::cloud::LogRecord::thread_id</definition>
239+
<argsstring/>
240+
<name>thread_id</name>
241+
<qualifiedname>google::cloud::LogRecord::thread_id</qualifiedname>
242+
<briefdescription>
243+
</briefdescription>
244+
<detaileddescription>
245+
</detaileddescription>
246+
<inbodydescription>
247+
</inbodydescription>
248+
<location file="log.h" line="156" column="19" bodyfile="log.h" bodystart="156" bodyend="-1"/>
249+
</memberdef>
250+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a949e7b4cb62d085ee13b107e63f83152" prot="public" static="no" mutable="no">
251+
<type>std::chrono::system_clock::time_point</type>
252+
<definition>std::chrono::system_clock::time_point google::cloud::LogRecord::timestamp</definition>
253+
<argsstring/>
254+
<name>timestamp</name>
255+
<qualifiedname>google::cloud::LogRecord::timestamp</qualifiedname>
256+
<briefdescription>
257+
</briefdescription>
258+
<detaileddescription>
259+
</detaileddescription>
260+
<inbodydescription>
261+
</inbodydescription>
262+
<location file="log.h" line="157" column="41" bodyfile="log.h" bodystart="157" bodyend="-1"/>
263+
</memberdef>
264+
<memberdef kind="variable" id="structgoogle_1_1cloud_1_1LogRecord_1a95652739567b944a4ffbbb6d31b3f2e0" prot="public" static="no" mutable="no">
265+
<type>std::string</type>
266+
<definition>std::string google::cloud::LogRecord::message</definition>
267+
<argsstring/>
268+
<name>message</name>
269+
<qualifiedname>google::cloud::LogRecord::message</qualifiedname>
270+
<briefdescription>
271+
</briefdescription>
272+
<detaileddescription>
273+
</detaileddescription>
274+
<inbodydescription>
275+
</inbodydescription>
276+
<location file="log.h" line="158" column="15" bodyfile="log.h" bodystart="158" bodyend="-1"/>
277+
</memberdef>
278+
</sectiondef>
279+
<briefdescription>
280+
<para>Represents a single log message.</para>
281+
</briefdescription>
282+
<detaileddescription>
283+
</detaileddescription>
284+
<collaborationgraph>
285+
<node id="1">
286+
<label>google::cloud::LogRecord</label>
287+
<link refid="structgoogle_1_1cloud_1_1LogRecord"/>
288+
<childnode refid="2" relation="usage">
289+
<edgelabel>filename</edgelabel>
290+
<edgelabel>function</edgelabel>
291+
<edgelabel>message</edgelabel>
292+
</childnode>
293+
</node>
294+
<node id="3">
295+
<label>std::basic_string&lt; Char &gt;</label>
296+
</node>
297+
<node id="2">
298+
<label>std::string</label>
299+
<childnode refid="3" relation="public-inheritance">
300+
</childnode>
301+
</node>
302+
</collaborationgraph>
303+
<location file="log.h" line="151" column="1" bodyfile="log.h" bodystart="151" bodyend="159"/>
304+
<listofallmembers>
305+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a46bc9a3adab542be80be9671d2ff82e6" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>filename</name></member>
306+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a8a04caf649e69b55404abf2d3b72d4a6" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>function</name></member>
307+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a29f2cf2bafa97addc548c26xx48a4fe0" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>lineno</name></member>
308+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a95652739567b944a4ffbbb6d31b3f2e0" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>message</name></member>
309+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a830f8xx5fe86e1581dddbbb2cd922cbc" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>severity</name></member>
310+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a9acea199684809e231263a486559f834" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>thread_id</name></member>
311+
<member refid="structgoogle_1_1cloud_1_1LogRecord_1a949e7b4cb62d085ee13b107e63f83152" prot="public" virt="non-virtual"><scope>google::cloud::LogRecord</scope><name>timestamp</name></member>
312+
</listofallmembers>
313+
</compounddef>
314+
</doxygen>)xml";
315+
174316
auto constexpr kNamespaceXml = R"xml(<?xml version="1.0" standalone="yes"?>
175317
<doxygen version="1.9.1" xml:lang="en-US">
176318
<compounddef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="namespacegoogle_1_1cloud_1_1mocks" kind="namespace" language="C++">
@@ -544,6 +686,48 @@ TEST(Doxygen2Yaml, Typedef) {
544686
EXPECT_EQ(actual, kExpected);
545687
}
546688

689+
TEST(Doxygen2Yaml, Variable) {
690+
auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
691+
items:
692+
- uid: structgoogle_1_1cloud_1_1LogRecord_1a830f8xx5fe86e1581dddbbb2cd922cbc
693+
name: |
694+
severity
695+
fullName: |
696+
google::cloud::LogRecord::severity
697+
id: structgoogle_1_1cloud_1_1LogRecord_1a830f8xx5fe86e1581dddbbb2cd922cbc
698+
parent: test-only-parent-id
699+
type: variable
700+
langs:
701+
- cpp
702+
syntax:
703+
contents: |
704+
Severity severity;
705+
source:
706+
id: severity
707+
path: google/cloud/log.h
708+
startLine: 152
709+
remote:
710+
repo: https://github.com/googleapis/google-cloud-cpp/
711+
branch: main
712+
path: google/cloud/log.h
713+
)yml";
714+
715+
pugi::xml_document doc;
716+
doc.load_string(kStruct2Xml);
717+
auto selected = doc.select_node(
718+
"//*[@id='"
719+
"structgoogle_1_1cloud_1_1LogRecord_1a830f8xx5fe86e1581dddbbb2cd922cbc"
720+
"']");
721+
ASSERT_TRUE(selected);
722+
YAML::Emitter yaml;
723+
StartDocFxYaml(yaml);
724+
YamlContext ctx;
725+
ctx.parent_id = "test-only-parent-id";
726+
ASSERT_TRUE(AppendIfVariable(yaml, ctx, selected.node()));
727+
auto const actual = EndDocFxYaml(yaml);
728+
EXPECT_EQ(actual, kExpected);
729+
}
730+
547731
TEST(Doxygen2Yaml, Function) {
548732
auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
549733
items:

0 commit comments

Comments
 (0)