Use gtk-doc con una configuración actualizada para la documentación de la API. (Consulte la )
Use XML entities for including external symbols into the documentation. ()
Use a consistent, standard, table of contents for all API documentation to maintain familiarity. ()
Use
Añada anotaciones de instrospección a toda la documentación de la API. (Consulte la )
Add Since lines to all API documentation.
()
Activar las pruebas de gtk-doc. ()
The preferred documentation system for GNOME libraries is gtk-doc, which extracts inline comments from the code to let you build a DocBook document and collection of HTML pages. These can then be read in Devhelp. A lot of GNOME’s infrastructure is built to handle with documentation written using gtk-doc.
To integrate gtk-doc into a project’s build system, follow the
instructions in the gtk-doc manual. Note that while the
gtk-doc’s no-tmpl flavour should be used, and XML mode should
be used instead of SGML. (tmpl mode and SGML are both outdated and slower
than XML.)
If the package version is needed to be substituted into the documentation,
create a file named
@PACKAGE_VERSION@
Add it to AC_CONFIG_FILES in <!ENTITY version SYSTEM "version.xml"> in the
DOCTYPE at the top of the document. The package version can
then be used inline as &version;.
Using a standard layout for the table of contents, sections, appendices,
etc. means the same
Se sugiere la siguiente distribución:
It is important to make the license used for API references clear, especially if they contain code examples which could be copied around.
Typically, projects use the same license for their API reference as for the project’s code itself, to avoid confusion. Some other projects use CC-BY-SA 3.0 for all their reference documentation. The choice is yours.
As shown in the Standard Layout you
should include a
Todas las API públicas deben tener comentarios de tipo gtk-doc. Para las funciones, estos se deben colocar en el código fuente, encima de la función.
/**
* gtk_get_flow:
* @widget: a #GtkWidget
*
* Gets the flow of a widget.
*
* Note that flows may be laminar or turbulent...
*
* Returns: (transfer none): the flow of @widget
*/
GtkFlow *
gtk_get_flow (GtkWidget *widget)
{
...
}
Documentation comments for macros, function types, class structs, etc. should be placed next to the definitions, typically in header files.
Section introductions should be placed in the source file they describe, after the license header:
/**
* SECTION:gtksizerequest
* @Short_Description: Height-for-width geometry management
* @Title: GtkSizeRequest
*
* The GtkSizeRequest interface is GTK+'s height-for-width (and
* width-for-height) geometry management system.
* ...
*/
Keep in mind that in order to include a function, macro,
function type, or struct type, it needs to be listed in your
documentation’s
To properly document a new class, it needs to be given its own
section in get_type() function for your class needs
to be listed in your
Each gtk-doc comment should have appropriate GObject introspection annotations. These are useful for two reasons:
They add important information about parameter types, nullability and memory management to the C API documentation generated by gtk-doc.
They allow public APIs to be automatically bound in other languages, such as Python or JavaScript.
Introspection annotations add information to APIs (functions, function parameters, function return values, structures, GObject properties, GObject signals) which is otherwise not present in the machine readable C API and only exists in the form of human readable documentation or convention. They are very important.
In gtk-doc comments, annotations should be preferred over human-readable
equivalents. For example, when documenting a function parameter which may
be NULL, use the (nullable) annotation rather
than some text:
/**
* my_function:
* @parameter: (nullable): some parameter which affects something
*
* Body of the function documentation.
*/
En lugar de:
/**
* my_bad_function:
* @parameter: some parameter which affects something, or %NULL to ignore
*
* Bad body of the function documentation.
*/
For more information on introspection, see the introspection guidelines.
Whenever a symbol is added to the public API, it should have a
documentation comment added. This comment should always contain a
Since line with the package version number of the release
which will first contain the new API. This should be the number currently
in
Por ejemplo:
/**
* my_function:
* @param: some parameter
*
* Body of the function documentation.
*
* Since: 0.5.0
*/
gtk-doc uses this information to generate indexes of the APIs added in
each release. These should be added to the main
<part>
<title>Appendices</title>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include>
</index>
<index id="api-index-deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include>
</index>
<index role="0.1.0">
<title>Index of new symbols in 0.1.0</title>
<xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include>
</index>
<!-- More versions here. -->
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</part>
D-Bus interface descriptions contain documentation comments, and these can
be extracted from the XML using
The DocBook files can be included in the main
<chapter>
<title>C Interfaces</title>
<partintro>
<para>C wrappers for the D-Bus interfaces.</para>
</partintro>
<xi:include href="xml/SomeDBusService.xml"/>
<xi:include href="xml/SomeOtherService.xml"/>
</chapter>
The generated XML files must be included in the content_files
variable in your gtk-doc builddir does
not equal the srcdir.)
gtk-doc comes with support for checking the documentation with some basic
tests. These check that all version indexes are included in the main
These tests should always be enabled, by adding the following to your
gtk-doc
TESTS = $(GTKDOC_CHECK)
Se ejecutarán como parte de