From: Philippe Proulx Date: Mon, 13 May 2024 17:08:50 +0000 (-0400) Subject: doc/api/libbabeltrace2/DoxygenLayout.xml: use `topics` tab X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=HEAD;ds=inline 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 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 7e40db87..0ceb53ca 100644 --- a/doc/api/libbabeltrace2/DoxygenLayout.xml +++ b/doc/api/libbabeltrace2/DoxygenLayout.xml @@ -6,7 +6,9 @@ + intro="List of all API reference pages:"/> + diff --git a/doc/api/libbabeltrace2/dox/api-fund.dox b/doc/api/libbabeltrace2/dox/api-fund.dox index 5b24faf4..8f742e73 100644 --- 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 -API reference modules +API reference 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 API reference modules always +The API reference pages 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 - API reference modules make it + API reference pages 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: -In the API reference, each module +In the API reference, 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 API reference modules +Because the API reference pages 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 API reference modules make +The API reference pages make this clear in the precondition section. Such objects always have a *_get_type() 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 API reference modules +The API reference pages 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 db258057..5aef881b 100644 --- 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 -trace IR (intermediate representation) modules -contain everything you need to represent tracing domain concepts and +trace IR (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 22c1e5d3..d5a096c1 100644 --- 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. -
API reference
+
API reference
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.
*/ diff --git a/include/babeltrace2-ctf-writer/object.h b/include/babeltrace2-ctf-writer/object.h index 9767eb3e..0191b34b 100644 --- a/include/babeltrace2-ctf-writer/object.h +++ b/include/babeltrace2-ctf-writer/object.h @@ -20,7 +20,7 @@ extern "C" { #include @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 reference counting of Babeltrace objects. diff --git a/include/babeltrace2/error-reporting.h b/include/babeltrace2/error-reporting.h index 29e53e16..0a257d19 100644 --- 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 7267e62f..7e59f665 100644 --- a/include/babeltrace2/graph/component-class-dev.h +++ b/include/babeltrace2/graph/component-class-dev.h @@ -32,11 +32,11 @@ A component class 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 methods. This module essentially +A component class has methods. 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 4fe692f2..64bccf3b 100644 --- a/include/babeltrace2/graph/component-class.h +++ b/include/babeltrace2/graph/component-class.h @@ -31,9 +31,9 @@ A component class 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 82ee1f2d..b7ddf89a 100644 --- 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 methods. This module essentially -offers: +A message iterator class has methods. 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 a73d6e1c..f634f888 100644 --- 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 81a0daeb..7598f539 100644 --- 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 366f7146..c0748059 100644 --- 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 42420d8e..e5760598 100644 --- 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 BT_PLUGIN_*() 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 BT_PLUGIN_*() 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.

\anchor api-plugin-dev-custom-plugin-id Custom plugin ID

diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h index 80c0e66b..030862ae 100644 --- 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 66ad5415..0f950600 100644 --- 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:
Major version