Skip to content

Commit 5a26d3d

Browse files
coryancoryan
authored
impl(docfx): generate separate file for enums (#11497)
The tooling at google expects enums to be generated as separate files. This adds a small loop in `main()` to generate the files. We need to remove the enum definitions from the previous yml files, or we get duplicate definitions. And to make the enumvalues visible we need to list them as children of the enum.
1 parent 0f670e6 commit 5a26d3d

3 files changed

Lines changed: 29 additions & 16 deletions

File tree

‎docfx/doxygen2docfx.cc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,15 @@ int main(int argc, char* argv[]) try {
5050
std::ofstream(id + ".yml") << docfx::Compound2Yaml(config, node);
5151
}
5252

53+
// Enums need to be generated in their own file or DocFX cannot create links
54+
// to them.
55+
for (auto const& i : doc.select_nodes("//memberdef[@kind='enum']")) {
56+
auto const node = i.node();
57+
if (!docfx::IncludeInPublicDocuments(config, node)) continue;
58+
auto const id = std::string{node.attribute("id").as_string()};
59+
std::ofstream(id + ".yml") << docfx::Compound2Yaml(config, node);
60+
}
61+
5362
return 0;
5463
} catch (std::exception const& ex) {
5564
std::cerr << "Standard exception thrown: " << ex.what() << "\n";

‎docfx/doxygen2yaml.cc‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -68,12 +68,13 @@ void CompoundRecurse(YAML::Emitter& yaml, YamlContext const& ctx,
6868
for (auto const child : node) {
6969
if (!IncludeInPublicDocuments(ctx.config, child)) continue;
7070
if (IgnoreForRecurse(child)) continue;
71+
// Enums need to get their own files, so never recurse in them:
72+
if (kind(child) == "enum") continue;
7173
if (AppendIfSectionDef(yaml, ctx, child)) continue;
7274
if (AppendIfNamespace(yaml, ctx, child)) continue;
7375
if (AppendIfClass(yaml, ctx, child)) continue;
7476
if (AppendIfStruct(yaml, ctx, child)) continue;
7577
if (AppendIfEnumValue(yaml, ctx, child)) continue;
76-
if (AppendIfEnum(yaml, ctx, child)) continue;
7778
if (AppendIfTypedef(yaml, ctx, child)) continue;
7879
if (AppendIfFriend(yaml, ctx, child)) continue;
7980
if (AppendIfVariable(yaml, ctx, child)) continue;
@@ -157,12 +158,12 @@ bool AppendIfEnumValue(YAML::Emitter& yaml, YamlContext const& ctx,
157158
auto const id = std::string_view{node.attribute("id").as_string()};
158159
auto const name = std::string_view{node.child("name").child_value()};
159160

160-
yaml << YAML::BeginMap //
161-
<< YAML::Key << "uid" << YAML::Value << id //
162-
<< YAML::Key << "name" << YAML::Value << YAML::Literal << name //
163-
<< YAML::Key << "id" << YAML::Value << id //
164-
<< YAML::Key << "parent" << YAML::Value << ctx.parent_id //
165-
<< YAML::Key << "type" << YAML::Value << "enumvalue" //
161+
yaml << YAML::BeginMap //
162+
<< YAML::Key << "uid" << YAML::Value << id //
163+
<< YAML::Key << "name" << YAML::Value << name //
164+
<< YAML::Key << "id" << YAML::Value << id //
165+
<< YAML::Key << "parent" << YAML::Value << ctx.parent_id //
166+
<< YAML::Key << "type" << YAML::Value << "enumvalue" //
166167
<< YAML::Key << "langs" << YAML::BeginSeq << "cpp" << YAML::EndSeq;
167168
AppendDescription(yaml, node);
168169
yaml << YAML::EndMap;
@@ -179,7 +180,7 @@ bool AppendIfEnum(YAML::Emitter& yaml, YamlContext const& ctx,
179180
std::string_view{node.child("qualifiedname").child_value()};
180181
yaml << YAML::BeginMap //
181182
<< YAML::Key << "uid" << YAML::Value << id //
182-
<< YAML::Key << "name" << YAML::Value << YAML::Literal << name //
183+
<< YAML::Key << "name" << YAML::Value << name //
183184
<< YAML::Key << "fullName" //
184185
<< YAML::Value << YAML::Literal << full_name //
185186
<< YAML::Key << "id" << YAML::Value << id //
@@ -188,6 +189,10 @@ bool AppendIfEnum(YAML::Emitter& yaml, YamlContext const& ctx,
188189
<< YAML::Key << "langs" << YAML::BeginSeq << "cpp" << YAML::EndSeq; //
189190
AppendEnumSyntax(yaml, ctx, node);
190191
AppendDescription(yaml, node);
192+
auto const children = Children(ctx, node);
193+
if (!children.empty()) {
194+
yaml << YAML::Key << "children" << YAML::Value << children;
195+
}
191196
yaml << YAML::EndMap;
192197
auto nested = ctx;
193198
nested.parent_id = id;

‎docfx/doxygen2yaml_test.cc‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -404,8 +404,7 @@ TEST(Doxygen2Yaml, EnumValue) {
404404
auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
405405
items:
406406
- uid: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9caf8bb1d9c7cccc450ecd06167c7422bfa
407-
name: |
408-
kIdempotent
407+
name: kIdempotent
409408
id: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9caf8bb1d9c7cccc450ecd06167c7422bfa
410409
parent: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9c
411410
type: enumvalue
@@ -436,8 +435,7 @@ TEST(Doxygen2Yaml, Enum) {
436435
auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
437436
items:
438437
- uid: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9c
439-
name: |
440-
Idempotency
438+
name: Idempotency
441439
fullName: |
442440
google::cloud::Idempotency
443441
id: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9c
@@ -487,9 +485,11 @@ TEST(Doxygen2Yaml, Enum) {
487485
- In some applications, creating a duplicate entry may
488486
be acceptable as the system will deduplicate them later. In such systems it may
489487
be preferable to retry the operation even though it is not idempotent.
488+
children:
489+
- namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9caf8bb1d9c7cccc450ecd06167c7422bfa
490+
- namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9cae75d33e94f2dc4028d4d67bdaab75190
490491
- uid: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9caf8bb1d9c7cccc450ecd06167c7422bfa
491-
name: |
492-
kIdempotent
492+
name: kIdempotent
493493
id: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9caf8bb1d9c7cccc450ecd06167c7422bfa
494494
parent: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9c
495495
type: enumvalue
@@ -498,8 +498,7 @@ TEST(Doxygen2Yaml, Enum) {
498498
summary: |
499499
The operation is idempotent and can be retried after a transient failure.
500500
- uid: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9cae75d33e94f2dc4028d4d67bdaab75190
501-
name: |
502-
kNonIdempotent
501+
name: kNonIdempotent
503502
id: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9cae75d33e94f2dc4028d4d67bdaab75190
504503
parent: namespacegoogle_1_1cloud_1a7d65fd569564712b7cfe652613f30d9c
505504
type: enumvalue

0 commit comments

Comments
 (0)