doc/api/libbabeltrace2/DoxygenLayout.xml: use `topics` tab

It looks like the Doxygen project decided [1] to use the "topic"
terminology instead of "module" to avoid confusion with C++20 modules.

Add a `topics` tab to `DoxygenLayout.xml` because otherwise that
navigation tab won't show up.

Leaving `modules` for older Doxygen versions.

Also changing all the "module" terms to "API"/"page" in the actual
documentation to completely part from the old "module" Doxygen concept.

[1]: https://github.com/doxygen/doxygen/commit/6d80fc7e5d03c259b1a7280972e0b28884217655

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I6f535c42c2bd5f55e5727a3245a2d744b28c187c
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12630

diff --git a/doc/api/libbabeltrace2/DoxygenLayout.xml b/doc/api/libbabeltrace2/DoxygenLayout.xml
index 7e40db87279f183ba8698d29a8b4ec172e357d3a..0ceb53cafbb995dc5c07b767ffa81db0ff66434d 100644 (file)
--- a/doc/api/libbabeltrace2/DoxygenLayout.xml
+++ b/doc/api/libbabeltrace2/DoxygenLayout.xml
@@ -6,7 +6,9 @@
     <tab type="user" visible="yes" url="@ref examples" title="Examples"/>
     <tab type="pages" visible="yes" title="All pages" intro=""/>
     <tab type="modules" visible="yes" title="API reference"
-      intro="List of all API reference modules:"/>
+      intro="List of all API reference pages:"/>
+    <tab type="topics" visible="yes" title="API reference"
+      intro="List of all API reference pages:"/>
   </navindex>
 
   <group>

diff --git a/doc/api/libbabeltrace2/dox/api-fund.dox b/doc/api/libbabeltrace2/dox/api-fund.dox
index 5b24faf4e3c2b76fdf3d3fe0f5a1a57dbf304484..8f742e73f042431ec40b9a8dd814a2622efc64e8 100644 (file)
--- a/doc/api/libbabeltrace2/dox/api-fund.dox
+++ b/doc/api/libbabeltrace2/dox/api-fund.dox
@@ -35,7 +35,7 @@ that it meets its
 when it returns.
 
 The function descriptions in the
-<a class="el" href="modules.html">API reference modules</a>
+<a class="el" href="topics.html">API reference</a>
 list all their preconditions and postconditions, if any.
 
 The libbabeltrace2 public functions offer a
@@ -126,7 +126,7 @@ object type A inherits an object type B, then you can use both the A and
 B API functions with an object of type A. For example, because an
 \bt_enum_fc \em is conceptually an \bt_int_fc, you can use any integer
 field class function with an enumeration field class.
-The <a class="el" href="modules.html">API reference modules</a> always
+The <a class="el" href="topics.html">API reference pages</a> always
 indicate the inheritance relations.
 
 @subsection api-fund-object-shared-unique Shared vs. unique objects
@@ -199,7 +199,7 @@ Some \bt_name objects are \em shared while some others are \em unique:
 
     Because you cannot get a new unique object reference, you \em must
     ensure that you own the unique object's owner to keep it alive. The
-    <a class="el" href="modules.html">API reference modules</a> make it
+    <a class="el" href="topics.html">API reference pages</a> make it
     clear, depending on the context, which
     shared object is the ultimate owner of a given unique object.
 
@@ -212,7 +212,7 @@ Some \bt_name objects are \em shared while some others are \em unique:
   </dd>
 </dl>
 
-In the <a class="el" href="modules.html">API reference</a>, each module
+In the <a class="el" href="topics.html">API reference</a>, each page
 indicates whether the documented objects are shared or unique.
 
 @subsection api-fund-freezing Object freezing
@@ -233,7 +233,7 @@ When an object becomes frozen, its contained objects, if any, also
 become frozen, recursively.
 
 There's no function to check whether or not a given object is frozen.
-Because the <a class="el" href="modules.html">API reference modules</a>
+Because the <a class="el" href="topics.html">API reference pages</a>
 document which functions freeze which objects,
 the "frozen" property is only useful for libbabeltrace2 to catch
 programming errors (\ref api-fund-pre-post "precondition checks").
@@ -264,7 +264,7 @@ be contained in some collection. For example, all \bt_val objects have
 the type #bt_value because an \bt_array_val can contain different
 types of values. You must be careful to only call the functions which
 apply to a specific type of such objects.
-The <a class="el" href="modules.html">API reference modules</a> make
+The <a class="el" href="topics.html">API reference pages</a> make
 this clear in the precondition section. Such objects always have a
 <code>*_get_type()</code> function to get the object's exact type
 enumerator. For example, bt_value_get_type() returns the type enumerator
@@ -374,7 +374,7 @@ if (status != BT_VALUE_COPY_STATUS_OK) {
 }
 @endcode
 
-The <a class="el" href="modules.html">API reference modules</a>
+The <a class="el" href="topics.html">API reference pages</a>
 document, for each function, what each return status enumerator means.
 
 Some functions return properties or objects by output parameter. When

diff --git a/doc/api/libbabeltrace2/dox/group-trace-ir.dox b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
index db258057ce58fbb1a6e6d25582f80ee2aa5e2a09..5aef881b4e0ae36c73c6cc1da571e03b6123a701 100644 (file)
--- a/doc/api/libbabeltrace2/dox/group-trace-ir.dox
+++ b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
@@ -8,8 +8,8 @@
     domain objects and concepts (contents of \bt_p_msg).
 
 The \bt_name
-<strong><em>trace IR</em></strong> (intermediate representation) modules
-contain everything you need to represent tracing domain concepts and
+<strong><em>trace IR</em></strong> (intermediate representation) API
+offers everything you need to represent tracing domain concepts and
 objects so that many \bt_p_comp, written by different authors, can
 exchange trace metadata and data.
 

diff --git a/doc/api/libbabeltrace2/dox/main-page.dox b/doc/api/libbabeltrace2/dox/main-page.dox
index 22c1e5d38a6bec6d705eee1a341706bdfa4daa34..d5a096c11a4fb9bff3b79b22f802296a17293caf 100644 (file)
--- a/doc/api/libbabeltrace2/dox/main-page.dox
+++ b/doc/api/libbabeltrace2/dox/main-page.dox
@@ -112,13 +112,13 @@ to learn even more about the \bt_name project and its core concepts.
     parts of the API to accomplish real tasks.
   </dd>
 
-  <dt><a class="el" href="modules.html">API reference</a></dt>
+  <dt><a class="el" href="topics.html">API reference</a></dt>
   <dd>
     Documents all the \bt_name C functions, definitions, macros,
     enumerators, and types.
 
-    Each documentation module describes its API thoroughly and how it's
-    related to other modules.
+    Each page describes its API thoroughly and how it's
+    related to other APIs.
   </dd>
 </dl>
 */

diff --git a/include/babeltrace2-ctf-writer/object.h b/include/babeltrace2-ctf-writer/object.h
index 9767eb3ef83be723d3cc82dbd806676dcb0947b8..0191b34b3e601ff6c03cb99b74ed8d6e00b6eed0 100644 (file)
--- a/include/babeltrace2-ctf-writer/object.h
+++ b/include/babeltrace2-ctf-writer/object.h
@@ -20,7 +20,7 @@ extern "C" {
 #include <babeltrace2-ctf-writer/object.h>
 @endcode
 
-The macros and functions of this module are everything that is needed
+The macros and functions of this API are everything that is needed
 to handle the <strong><em>reference counting</em></strong> of
 Babeltrace objects.
 

diff --git a/include/babeltrace2/error-reporting.h b/include/babeltrace2/error-reporting.h
index 29e53e16b5d3b18fff9973855823d9f1b47bc57d..0a257d19340afab9c6fb182595db6e2a9218129c 100644 (file)
--- a/include/babeltrace2/error-reporting.h
+++ b/include/babeltrace2/error-reporting.h
@@ -28,8 +28,8 @@ extern "C" {
 @brief
     Error reporting functions and macros.
 
-This module contains functions and macros to report rich errors from a
-user function (a \bt_comp_cls method, a
+This API offers functions and macros to report rich
+errors from a user function (a \bt_comp_cls method, a
 \ref api-qexec "query operation", or a trace processing \bt_graph
 listener, for example) to any function caller.
 

diff --git a/include/babeltrace2/graph/component-class-dev.h b/include/babeltrace2/graph/component-class-dev.h
index 7267e62f1fe95df1ff69f3f7c315083bf2b49570..7e59f6655cafde816834153107fa5f05fb719335 100644 (file)
--- a/include/babeltrace2/graph/component-class-dev.h
+++ b/include/babeltrace2/graph/component-class-dev.h
@@ -32,11 +32,11 @@ A <strong><em>component class</em></strong> is the class of a \bt_comp:
 @image html component.png
 
 @attention
-    This module (component class development API) offers functions to
+    This API (component class development API) offers functions to
     programmatically create component classes. To get the properties of
     an existing component class, see \ref api-comp-cls.
 
-A component class has <em>methods</em>. This module essentially
+A component class has <em>methods</em>. This API essentially
 offers:
 
 - Component class method type definitions.
@@ -84,7 +84,7 @@ See \ref api-comp-cls-dev-methods "Methods" to learn more about the
 different types of component class methods.
 
 A component class is a \ref api-fund-shared-object "shared object": see
-the \ref api-comp-cls module for the reference count functions.
+the \ref api-comp-cls API for the reference count functions.
 
 Some library functions \ref api-fund-freezing "freeze" component classes
 on success. The documentation of those functions indicate this

diff --git a/include/babeltrace2/graph/component-class.h b/include/babeltrace2/graph/component-class.h
index 4fe692f2c88110a112ad9abfe82252253131e0fb..64bccf3b048d731f95fcb8a8e5b023931e4f781e 100644 (file)
--- a/include/babeltrace2/graph/component-class.h
+++ b/include/babeltrace2/graph/component-class.h
@@ -31,9 +31,9 @@ A <strong><em>component class</em></strong> is the class of a \bt_comp:
 @image html component.png
 
 @attention
-    This module (component class API) offers basic, read-only functions
-    to get component class properties. To \em create a component class,
-    see \ref api-comp-cls-dev or \ref api-plugin-dev.
+    This API (component class API) offers basic,
+    read-only functions to get component class properties. To \em create
+    a component class, see \ref api-comp-cls-dev or \ref api-plugin-dev.
 
 You can instantiate a given component class many times, with different
 initialization parameters, to create many components with the

diff --git a/include/babeltrace2/graph/message-iterator-class.h b/include/babeltrace2/graph/message-iterator-class.h
index 82ee1f2d6e4cdb579f1859d1c3977526fe06a146..b7ddf89ace35eea51acb9895a81af8a45ec40cbb 100644 (file)
--- a/include/babeltrace2/graph/message-iterator-class.h
+++ b/include/babeltrace2/graph/message-iterator-class.h
@@ -39,8 +39,8 @@ pass it to bt_component_class_source_create() or
 bt_component_class_filter_create() to set it as the created component
 class's message iterator class.
 
-A message iterator class has <em>methods</em>. This module essentially
-offers:
+A message iterator class has <em>methods</em>. This API
+essentially offers:
 
 - Message iterator class method type definitions.
 

diff --git a/include/babeltrace2/graph/message.h b/include/babeltrace2/graph/message.h
index a73d6e1cc240d7053e0af421d32d9d902e992c9f..f634f888fc7bc3bf1a5b249bb054d576a021afb9 100644 (file)
--- a/include/babeltrace2/graph/message.h
+++ b/include/babeltrace2/graph/message.h
@@ -848,7 +848,7 @@ version as rarely as possible. When it is required, though, it's a
 welcome tool to make the project evolve gracefully.
 
 The Message Interchange Protocol has no dedicated documentation as this
-very message module (and its submodules, like \ref api-tir)
+very message API (and its contained APIs, like \ref api-tir)
 documentation is enough. You can consider that all the
 functions of the message and trace IR objects have an implicit MIP
 version \ref api-fund-pre-post "precondition". When a given

diff --git a/include/babeltrace2/graph/private-query-executor.h b/include/babeltrace2/graph/private-query-executor.h
index 81a0daeb0cdf863d9db8a60a3752bf5556e7d669..7598f5397e4c893d072dcfa1521d35d1a8e82cbb 100644 (file)
--- a/include/babeltrace2/graph/private-query-executor.h
+++ b/include/babeltrace2/graph/private-query-executor.h
@@ -35,7 +35,7 @@ from within a \bt_comp_cls
 A query method receives a private query executor as its
 \bt_p{query_executor} parameter.
 
-As of \bt_name_version_min_maj, this module only offers the
+As of \bt_name_version_min_maj, this API only offers the
 bt_private_query_executor_as_query_executor_const() function to
 \ref api-fund-c-typing "upcast" a private query executor to a
 \c const query executor. You need this to get the query executor's

diff --git a/include/babeltrace2/graph/self-component-class.h b/include/babeltrace2/graph/self-component-class.h
index 366f7146f26388a26c578588ddbac6f9a8b1a949..c07480596329c785ba12342af20d7448a962ab14 100644 (file)
--- a/include/babeltrace2/graph/self-component-class.h
+++ b/include/babeltrace2/graph/self-component-class.h
@@ -31,9 +31,9 @@ The #bt_self_component_class, #bt_self_component_class_source,
 private views of a \bt_comp_cls from within a component class
 \ref api-comp-cls-dev-class-meth "class method".
 
-As of \bt_name_version_min_maj, this module only contains functions
-to \ref api-fund-c-typing "upcast" the "self" (private) types to their
-public #bt_component_class, #bt_component_class_source,
+As of \bt_name_version_min_maj, this API only offers
+functions to \ref api-fund-c-typing "upcast" the "self" (private) types
+to their public #bt_component_class, #bt_component_class_source,
 #bt_component_class_filter, and #bt_component_class_sink counterparts.
 */
 

diff --git a/include/babeltrace2/plugin/plugin-dev.h b/include/babeltrace2/plugin/plugin-dev.h
index 42420d8e2da5da937ccb3415471900a5c666aff5..e5760598badeaa7f3b2c717bd6934a8317123c7c 100644 (file)
--- a/include/babeltrace2/plugin/plugin-dev.h
+++ b/include/babeltrace2/plugin/plugin-dev.h
@@ -49,13 +49,14 @@ extern "C" {
 @brief
     Shared object plugin development.
 
-This module offers macros to create a \bt_name shared object plugin.
+This API offers macros to create a \bt_name shared
+object plugin.
 
-Behind the scenes, the <code>BT_PLUGIN_*()</code> macros of this module
-create and fill global tables which are located in sections of the
-shared object with specific names. The \ref api-plugin functions can
-load the resulting shared object file and create corresponding
-\bt_plugin objects.
+Behind the scenes, the <code>BT_PLUGIN_*()</code> macros of this
+API create and fill global tables which are located in
+sections of the shared object with specific names. The \ref api-plugin
+functions can load the resulting shared object file and create
+corresponding \bt_plugin objects.
 
 See \ref guide-comp-link-plugin-so.
 
@@ -192,7 +193,7 @@ You can repeat steps 5 to 7 to add more than one component class to a
 given plugin.
 
 See \ref example-simple-plugin-def-file for a concrete example of how
-to use the macros of this module.
+to use the macros of this API.
 
 <h1>\anchor api-plugin-dev-custom-plugin-id Custom plugin ID</h1>
 

diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h
index 80c0e66bde5e4bf5820310c072dff3a8485b79c9..030862ae2b9b2b50178108d03f76cd4b1d319c44 100644 (file)
--- a/include/babeltrace2/util.h
+++ b/include/babeltrace2/util.h
@@ -25,7 +25,7 @@ extern "C" {
 @brief
     General purpose utilities.
 
-This module contains general purpose utilities.
+This API offers general purpose utilities.
 */
 
 /*! @{ */

diff --git a/include/babeltrace2/version.h b/include/babeltrace2/version.h
index 66ad5415d07fd5c7b3d55ae6561649dc9a22873d..0f9506001cf83117efd46556dbf9a865274384df 100644 (file)
--- a/include/babeltrace2/version.h
+++ b/include/babeltrace2/version.h
@@ -23,8 +23,8 @@ extern "C" {
 @brief
     Library version getters.
 
-This module contains functions to get information about the library's
-version:
+This API offers functions to get information about the
+library's version:
 
 <dl>
   <dt>Major version</dt>