Skip to content

Commit 16f6848

Browse files
coryancoryan
authored
refactor(docfx): split LinkedTextType() (#11584)
1 parent b637e71 commit 16f6848

7 files changed

Lines changed: 144 additions & 35 deletions

File tree

‎docfx/CMakeLists.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ add_library(
5555
function_classifiers.h
5656
generate_metadata.cc
5757
generate_metadata.h
58+
linked_text_type.cc
59+
linked_text_type.h
5860
parse_arguments.cc
5961
parse_arguments.h
6062
public_docs.cc
@@ -102,6 +104,7 @@ set(unit_tests
102104
doxygen_pages_test.cc
103105
function_classifiers_test.cc
104106
generate_metadata_test.cc
107+
linked_text_type_test.cc
105108
parse_arguments_test.cc
106109
public_docs_test.cc
107110
yaml_context_test.cc)

‎docfx/docfx.bzl‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ docfx_hdrs = [
2929
"doxygen_pages.h",
3030
"function_classifiers.h",
3131
"generate_metadata.h",
32+
"linked_text_type.h",
3233
"parse_arguments.h",
3334
"public_docs.h",
3435
"toc_entry.h",
@@ -48,6 +49,7 @@ docfx_srcs = [
4849
"doxygen_pages.cc",
4950
"function_classifiers.cc",
5051
"generate_metadata.cc",
52+
"linked_text_type.cc",
5153
"parse_arguments.cc",
5254
"public_docs.cc",
5355
"toc_entry.cc",

‎docfx/doxygen2syntax.cc‎

Lines changed: 1 addition & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
#include "docfx/doxygen2markdown.h"
1717
#include "docfx/doxygen_errors.h"
1818
#include "docfx/function_classifiers.h"
19+
#include "docfx/linked_text_type.h"
1920
#include "docfx/yaml_emit.h"
2021

2122
namespace docfx {
@@ -48,41 +49,6 @@ void AppendLocation(YAML::Emitter& yaml, YamlContext const& ctx,
4849
<< YAML::EndMap; // source
4950
}
5051

51-
// A `linkedTextType` is defined as below. It is basically a sequence of
52-
// references (links) mixed with plain text. We ignore the references in the
53-
// formatting of the syntax content.
54-
//
55-
// clang-format off
56-
// <xsd:complexType name="linkedTextType" mixed="true">
57-
// <xsd:sequence>
58-
// <xsd:element name="ref" type="refTextType" minOccurs="0" maxOccurs="unbounded" />
59-
// </xsd:sequence>
60-
// </xsd:complexType>
61-
// ... ..
62-
// <xsd:complexType name="refTextType">
63-
// <xsd:simpleContent>
64-
// <xsd:extension base="xsd:string">
65-
// <xsd:attribute name="refid" type="xsd:string" />
66-
// <xsd:attribute name="kindref" type="DoxRefKind" />
67-
// <xsd:attribute name="external" type="xsd:string" use="optional"/>
68-
// <xsd:attribute name="tooltip" type="xsd:string" use="optional"/>
69-
// </xsd:extension>
70-
// </xsd:simpleContent>
71-
// </xsd:complexType>
72-
// clang-format on
73-
std::string LinkedTextType(pugi::xml_node node) {
74-
std::ostringstream os;
75-
for (auto const child : node) {
76-
auto const name = std::string_view{child.name()};
77-
if (name == "ref") {
78-
os << child.child_value();
79-
} else {
80-
os << child.value();
81-
}
82-
}
83-
return std::move(os).str();
84-
}
85-
8652
std::string HtmlEscape(std::string_view text) {
8753
std::string clean;
8854
for (auto c : text) {

‎docfx/linked_text_type.cc‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#include "docfx/linked_text_type.h"
16+
#include <sstream>
17+
#include <string_view>
18+
19+
namespace docfx {
20+
21+
// A `linkedTextType` is defined as below. It is basically a sequence of
22+
// references (links) mixed with plain text. We ignore the references in the
23+
// formatting of the syntax content.
24+
//
25+
// clang-format off
26+
// <xsd:complexType name="linkedTextType" mixed="true">
27+
// <xsd:sequence>
28+
// <xsd:element name="ref" type="refTextType" minOccurs="0" maxOccurs="unbounded" />
29+
// </xsd:sequence>
30+
// </xsd:complexType>
31+
// ... ..
32+
// <xsd:complexType name="refTextType">
33+
// <xsd:simpleContent>
34+
// <xsd:extension base="xsd:string">
35+
// <xsd:attribute name="refid" type="xsd:string" />
36+
// <xsd:attribute name="kindref" type="DoxRefKind" />
37+
// <xsd:attribute name="external" type="xsd:string" use="optional"/>
38+
// <xsd:attribute name="tooltip" type="xsd:string" use="optional"/>
39+
// </xsd:extension>
40+
// </xsd:simpleContent>
41+
// </xsd:complexType>
42+
// clang-format on
43+
std::string LinkedTextType(pugi::xml_node node) {
44+
std::ostringstream os;
45+
for (auto const child : node) {
46+
auto const name = std::string_view{child.name()};
47+
os << (name == "ref" ? child.child_value() : child.value());
48+
}
49+
return std::move(os).str();
50+
}
51+
52+
} // namespace docfx

‎docfx/linked_text_type.h‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#ifndef GOOGLE_CLOUD_CPP_DOCFX_LINKED_TEXT_TYPE_H
16+
#define GOOGLE_CLOUD_CPP_DOCFX_LINKED_TEXT_TYPE_H
17+
18+
#include <pugixml.hpp>
19+
#include <string>
20+
21+
namespace docfx {
22+
23+
/**
24+
* Returns an element of type `linkedTextType` as a simple string.
25+
*
26+
* Doxygen nodes of `linkedTextType` appear in many contexts. We often need to
27+
* format them as simple strings as they appear in the name of documented
28+
* elements, including function prototypes and template parameters.
29+
*/
30+
std::string LinkedTextType(pugi::xml_node node);
31+
32+
} // namespace docfx
33+
34+
#endif // GOOGLE_CLOUD_CPP_DOCFX_LINKED_TEXT_TYPE_H

‎docfx/linked_text_type_test.cc‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#include "docfx/linked_text_type.h"
16+
#include <gmock/gmock.h>
17+
18+
namespace docfx {
19+
namespace {
20+
21+
TEST(LinkedTextType, Basic) {
22+
auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
23+
<doxygen version="1.9.1" xml:lang="en-US">
24+
<type id="001"><ref refid="classgoogle_1_1cloud_1_1ErrorInfo" kindref="compound">ErrorInfo</ref> const &amp;</type>
25+
<type id="002">std::string</type>
26+
</doxygen>)xml";
27+
pugi::xml_document doc;
28+
doc.load_string(kXml);
29+
30+
struct TestCase {
31+
std::string id;
32+
std::string expected;
33+
} const cases[] = {
34+
{"001", "ErrorInfo const &"},
35+
{"002", "std::string"},
36+
};
37+
38+
auto vars = pugi::xpath_variable_set();
39+
vars.add("id", pugi::xpath_type_string);
40+
auto query = pugi::xpath_query("//*[@id = string($id)]", &vars);
41+
for (auto const& test : cases) {
42+
SCOPED_TRACE("Running with id=" + test.id);
43+
vars.set("id", test.id.c_str());
44+
auto selected = doc.select_node(query);
45+
ASSERT_TRUE(selected);
46+
EXPECT_EQ(test.expected, LinkedTextType(selected.node()));
47+
}
48+
}
49+
50+
} // namespace
51+
} // namespace docfx

‎docfx/unit_tests.bzl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ unit_tests = [
2727
"doxygen_pages_test.cc",
2828
"function_classifiers_test.cc",
2929
"generate_metadata_test.cc",
30+
"linked_text_type_test.cc",
3031
"parse_arguments_test.cc",
3132
"public_docs_test.cc",
3233
"yaml_context_test.cc",

0 commit comments

Comments
 (0)