Skip to content

Commit b516479

Browse files
eramongodberamongodb
authored
CXX-3085 Upgrade to Doxygen 1.11.0 (#1185)
* doxygen: upgrade to 1.11.0 * doxygen: set MARKDOWN_ID_STYLE = GITHUB * doxygen: add TODO to WARN_IF_UNDOC_ENUM_VAL * doxygen: set HTML_COLORSTYLE = LIGHT * doxygen: set SHOW_HEADERFILE = NO * docs: revert workaround for Doxygen inline function overload confusion * doxygen: use SHOW_HEADERFILE in place of SHOW_USED_FILES * Rename root fwd.hpp to doc.hpp and exclude from install commands * Exclude doc headers from macro guard tests
1 parent 1c74ce0 commit b516479

File tree

15 files changed

+566
-312
lines changed

15 files changed

+566
-312
lines changed

‎Doxyfile‎

Lines changed: 475 additions & 236 deletions
Large diffs are not rendered by default.

‎docs/DoxygenLayout.xml‎

Lines changed: 61 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,43 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
12
<doxygenlayout version="1.0">
2-
<!-- Generated by doxygen 1.9.1 -->
3+
<!-- Generated by doxygen 1.11.0 -->
34
<!-- Navigation index tabs for HTML output -->
45
<navindex>
56
<tab type="mainpage" visible="yes" title=""/>
67
<tab type="files" visible="yes" title="">
78
<tab type="filelist" visible="yes" title="" intro=""/>
89
<tab type="globals" visible="yes" title="" intro=""/>
910
</tab>
11+
<tab type="modules" visible="yes">
12+
<tab type="modulelist" visible="yes" title="" intro=""/>
13+
<tab type="modulemembers" visible="yes" title="" intro=""/>
14+
</tab>
1015
<tab type="namespaces" visible="yes" title="">
1116
<tab type="namespacelist" visible="yes" title="" intro=""/>
1217
<tab type="namespacemembers" visible="yes" title="" intro=""/>
1318
</tab>
19+
<tab type="concepts" visible="yes" title="">
20+
</tab>
21+
<tab type="interfaces" visible="yes" title="">
22+
<tab type="interfacelist" visible="yes" title="" intro=""/>
23+
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
24+
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
25+
</tab>
1426
<tab type="classes" visible="yes" title="">
1527
<tab type="classlist" visible="yes" title="" intro=""/>
16-
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
28+
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
1729
<tab type="hierarchy" visible="yes" title="" intro=""/>
1830
<tab type="classmembers" visible="yes" title="" intro=""/>
1931
</tab>
20-
<tab type="modules" visible="yes" title="Groups" intro="Pages documenting groups of related entities."/>
32+
<tab type="topics" visible="yes" title="Groups" intro="Pages documenting groups of related entities."/>
2133
<tab type="pages" visible="yes" title="Topics" intro="Pages documenting topics related to the API."/>
22-
<tab type="interfaces" visible="no" title="Unused">
23-
<tab type="interfacelist" visible="yes" title="" intro=""/>
24-
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
25-
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
26-
</tab>
27-
<tab type="structs" visible="no" title="Unused">
34+
<tab type="structs" visible="yes" title="">
2835
<tab type="structlist" visible="yes" title="" intro=""/>
29-
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
36+
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
3037
</tab>
3138
<tab type="exceptions" visible="no" title="Unused">
3239
<tab type="exceptionlist" visible="yes" title="" intro=""/>
33-
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
40+
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
3441
<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
3542
</tab>
3643
<tab type="examples" visible="no" title="Unused" intro=""/>
@@ -39,11 +46,10 @@
3946
<!-- Layout definition for a class page -->
4047
<class>
4148
<briefdescription visible="no"/>
49+
<includes visible="$SHOW_HEADERFILE"/>
4250
<detaileddescription title="Description"/>
43-
<usedfiles visible="$SHOW_USED_FILES"/>
44-
<includes visible="$SHOW_INCLUDE_FILES"/>
45-
<inheritancegraph visible="$CLASS_GRAPH"/>
46-
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
51+
<inheritancegraph visible="yes"/>
52+
<collaborationgraph visible="yes"/>
4753
<memberdecl>
4854
<nestedclasses visible="yes" title=""/>
4955
<publictypes title=""/>
@@ -92,6 +98,7 @@
9298
<events title=""/>
9399
</memberdef>
94100
<allmemberslink visible="yes"/>
101+
<usedfiles visible="$SHOW_USED_FILES"/>
95102
<authorsection visible="yes"/>
96103
</class>
97104

@@ -104,6 +111,7 @@
104111
<constantgroups visible="yes" title=""/>
105112
<interfaces visible="yes" title=""/>
106113
<classes visible="yes" title=""/>
114+
<concepts visible="yes" title=""/>
107115
<structs visible="yes" title=""/>
108116
<exceptions visible="yes" title=""/>
109117
<typedefs title=""/>
@@ -112,6 +120,7 @@
112120
<enums title=""/>
113121
<functions title=""/>
114122
<variables title=""/>
123+
<properties title=""/>
115124
<membergroups visible="yes"/>
116125
</memberdecl>
117126
<memberdef>
@@ -122,24 +131,35 @@
122131
<enums title=""/>
123132
<functions title=""/>
124133
<variables title=""/>
134+
<properties title=""/>
125135
</memberdef>
126136
<authorsection visible="yes"/>
127137
</namespace>
128138

139+
<!-- Layout definition for a concept page -->
140+
<concept>
141+
<briefdescription visible="yes"/>
142+
<includes visible="$SHOW_HEADERFILE"/>
143+
<definition visible="yes" title=""/>
144+
<detaileddescription title=""/>
145+
<authorsection visible="yes"/>
146+
</concept>
147+
129148
<!-- Layout definition for a file page -->
130149
<file>
131150
<briefdescription visible="no"/>
132151
<detaileddescription title="Description"/>
133152
<includes visible="$SHOW_INCLUDE_FILES"/>
134-
<includegraph visible="$INCLUDE_GRAPH"/>
135-
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
153+
<includegraph visible="yes"/>
154+
<includedbygraph visible="yes"/>
136155
<sourcelink visible="yes"/>
137156
<memberdecl>
138157
<interfaces visible="yes" title=""/>
139158
<classes visible="yes" title=""/>
140159
<structs visible="yes" title=""/>
141160
<exceptions visible="yes" title=""/>
142161
<namespaces visible="yes" title=""/>
162+
<concepts visible="yes" title=""/>
143163
<constantgroups visible="yes" title=""/>
144164
<defines title=""/>
145165
<typedefs title=""/>
@@ -148,6 +168,7 @@
148168
<enums title=""/>
149169
<functions title=""/>
150170
<variables title=""/>
171+
<properties title=""/>
151172
<membergroups visible="yes"/>
152173
</memberdecl>
153174
<memberdef>
@@ -159,6 +180,7 @@
159180
<enums title=""/>
160181
<functions title=""/>
161182
<variables title=""/>
183+
<properties title=""/>
162184
</memberdef>
163185
<authorsection/>
164186
</file>
@@ -167,12 +189,14 @@
167189
<group>
168190
<briefdescription visible="no"/>
169191
<detaileddescription title="Description"/>
170-
<groupgraph visible="$GROUP_GRAPHS"/>
192+
<groupgraph visible="yes"/>
171193
<memberdecl>
172194
<nestedgroups visible="yes" title=""/>
195+
<modules visible="yes" title=""/>
173196
<dirs visible="yes" title=""/>
174197
<files visible="yes" title=""/>
175198
<namespaces visible="yes" title=""/>
199+
<concepts visible="yes" title=""/>
176200
<classes visible="yes" title=""/>
177201
<defines title=""/>
178202
<typedefs title=""/>
@@ -213,6 +237,25 @@
213237
<authorsection visible="yes"/>
214238
</group>
215239

240+
<!-- Layout definition for a C++20 module page -->
241+
<module>
242+
<briefdescription visible="yes"/>
243+
<exportedmodules visible="yes"/>
244+
<memberdecl>
245+
<concepts visible="yes" title=""/>
246+
<classes visible="yes" title=""/>
247+
<enums title=""/>
248+
<typedefs title=""/>
249+
<functions title=""/>
250+
<variables title=""/>
251+
<membergroups title=""/>
252+
</memberdecl>
253+
<detaileddescription title=""/>
254+
<memberdecl>
255+
<files visible="yes"/>
256+
</memberdecl>
257+
</module>
258+
216259
<!-- Layout definition for a directory page -->
217260
<directory>
218261
<briefdescription visible="no"/>

‎etc/generate-apidocs-from-tag.pl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
# The required Doxygen version.
1313
# The generated results are sensitive to the release version.
14-
our $doxygen_version_required = "1.9.1";
14+
our $doxygen_version_required = "1.11.0";
1515

1616
# Allow specifying a custom Doxygen binary via the `$DOXYGEN_BINARY` environment variable.
1717
our $doxygen_binary = $ENV{DOXYGEN_BINARY} || "doxygen";

‎src/bsoncxx/include/CMakeLists.txt‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,9 @@
1515
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/
1616
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
1717
COMPONENT dev
18-
FILES_MATCHING PATTERN "*.hpp"
18+
FILES_MATCHING
19+
PATTERN "*.hpp"
20+
PATTERN "bsoncxx/doc.hpp" EXCLUDE
1921
)
2022

2123
file(GLOB_RECURSE bsoncxx_include_headers

‎src/bsoncxx/include/bsoncxx/fwd.hpp‎ renamed to ‎src/bsoncxx/include/bsoncxx/doc.hpp‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,7 @@
2020
/// @file
2121
/// For documentation purposes only.
2222
///
23-
/// This header is not intended to be includable.
24-
///
25-
/// @note This header is shadowed by @ref bsoncxx/v_noabi/bsoncxx/fwd.hpp per include directory
26-
/// search ordering.
23+
/// @note This header is not includable!
2724
///
2825

2926
///

‎src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/helpers.hpp‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,11 @@ namespace builder {
5555
namespace basic {
5656

5757
/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::document::view_or_value doc)
58-
/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
59-
/// v_noabi::builder::concatenate_array is also declared in this scope.
6058
v_noabi::concatenate_doc concatenate(v_noabi::document::view_or_value doc);
6159

60+
/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::array::view_or_value doc)
61+
v_noabi::concatenate_doc concatenate(v_noabi::array::view_or_value doc);
62+
6263
} // namespace basic
6364
} // namespace builder
6465
} // namespace bsoncxx

‎src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -93,19 +93,25 @@ struct concatenate_array {
9393
///
9494
/// @see bsoncxx::v_noabi::builder::concatenate_doc
9595
///
96-
/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
97-
/// v_noabi::builder::concatenate_array is also declared in this scope.
98-
///
9996
BSONCXX_INLINE concatenate_doc concatenate(document::view_or_value doc) {
10097
return {std::move(doc)};
10198
}
10299

103-
// Why is Doxygen unable to parse this overload correctly???
104-
// @cond DOXYGEN_DISABLE "warning: no matching file member found for ..."
100+
///
101+
/// Helper method to concatenate an array.
102+
///
103+
/// Use this with the document stream builder to merge an existing array's fields with a new
104+
/// document's.
105+
///
106+
/// @param array The array to concatenate.
107+
///
108+
/// @return concatenate_doc A concatenating struct.
109+
///
110+
/// @see bsoncxx::v_noabi::builder::concatenate_doc
111+
///
105112
BSONCXX_INLINE concatenate_array concatenate(array::view_or_value array) {
106113
return {std::move(array)};
107114
}
108-
// @endcond
109115

110116
} // namespace builder
111117
} // namespace v_noabi
@@ -131,11 +137,12 @@ using ::bsoncxx::v_noabi::builder::concatenate;
131137
namespace bsoncxx {
132138
namespace builder {
133139

134-
/// @ref bsoncxx::v_noabi::builder::concatenate
135-
/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
136-
/// v_noabi::builder::concatenate_array is also declared in this scope.
140+
/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::document::view_or_value doc)
137141
v_noabi::builder::concatenate_doc concatenate(v_noabi::document::view_or_value doc);
138142

143+
/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::array::view_or_value doc)
144+
v_noabi::builder::concatenate_doc concatenate(v_noabi::array::view_or_value doc);
145+
139146
} // namespace builder
140147
} // namespace bsoncxx
141148

‎src/bsoncxx/lib/CMakeLists.txt‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@ set(bsoncxx_sources_v_noabi
3535

3636
list(APPEND bsoncxx_sources
3737
${bsoncxx_sources_v_noabi}
38-
bsoncxx/fwd.cpp
3938
)
4039
list(TRANSFORM bsoncxx_sources PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
4140
set(bsoncxx_sources "${bsoncxx_sources}" PARENT_SCOPE)
@@ -71,7 +70,6 @@ endif()
7170
set_dist_list(src_bsoncxx_lib_DIST
7271
CMakeLists.txt
7372
${bsoncxx_sources_v_noabi}
74-
bsoncxx/fwd.cpp
7573
bsoncxx/v_noabi/bsoncxx/config/config.hpp.in
7674
bsoncxx/v_noabi/bsoncxx/config/private/config.hh.in
7775
bsoncxx/v_noabi/bsoncxx/config/private/postlude.hh

‎src/bsoncxx/lib/bsoncxx/fwd.cpp‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎src/bsoncxx/test/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ if(ENABLE_MACRO_GUARD_TESTS)
123123
"lib/*.hh" # Private headers.
124124
"test/*.hh" # Test headers.
125125
EXCLUDE_REGEXES
126+
"include/bsoncxx/doc\.hpp" # Doc header.
126127
"(include|lib)/.*/(prelude|postlude)\.(hpp|hh)" # Macro guard headers.
127128
"(include|lib)/bsoncxx/v_noabi/bsoncxx/config/.*" # v_noabi config headers.
128129
"include/bsoncxx/v_noabi/bsoncxx/enums/.*" # v_noabi X-macro headers.

0 commit comments

Comments
 (0)