|
Packit |
1470ea |
|
|
Packit |
1470ea |
xmlns:its="http://www.w3.org/2005/11/its"
|
|
Packit |
1470ea |
xmlns:xi="http://www.w3.org/2003/XInclude"
|
|
Packit |
1470ea |
type="topic"
|
|
Packit |
1470ea |
id="documentation">
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<info>
|
|
Packit |
1470ea |
<link type="guide" xref="index#general-guidelines"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Federico Mena-Quintero</name>
|
|
Packit |
1470ea |
<email its:translate="no">federico@gnome.org</email>
|
|
Packit |
1470ea |
<years>2013</years>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Philip Withnall</name>
|
|
Packit |
1470ea |
<email its:translate="no">philip.withnall@collabora.co.uk</email>
|
|
Packit |
1470ea |
<years>2015</years>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>The GTK+ Team</name>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<desc>Adding documentation to libraries and APIs</desc>
|
|
Packit |
1470ea |
</info>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<title>Documentation</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<synopsis>
|
|
Packit |
1470ea |
<title>Summary</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Use gtk-doc with up-to-date settings for API documentation.
|
|
Packit |
1470ea |
(<link xref="#gtk-doc"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Use XML entities for including external symbols into the documentation.
|
|
Packit |
1470ea |
(<link xref="#build-system"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Use a consistent, standard, table of contents for all API documentation
|
|
Packit |
1470ea |
to maintain familiarity. (<link xref="#standard-layout"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to
|
|
Packit |
1470ea |
include in the gtk-doc build. (<link xref="#dbus-api"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Add introspection annotations to all API documentation.
|
|
Packit |
1470ea |
(<link xref="#introspection-annotations"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Add Since lines to all API documentation.
|
|
Packit |
1470ea |
(<link xref="#symbol-versioning"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Enable gtk-doc tests. (<link xref="#keeping-up-to-date"/>)
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
</synopsis>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="gtk-doc">
|
|
Packit |
1470ea |
<title>gtk-doc</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The preferred documentation system for GNOME libraries is
|
|
Packit |
1470ea |
href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, which
|
|
Packit |
1470ea |
extracts inline comments from the code to let you build a
|
|
Packit |
1470ea |
href="http://docbook.org/">DocBook</link> document and collection of HTML
|
|
Packit |
1470ea |
pages. These can then be read in
|
|
Packit |
1470ea |
<link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. A lot of
|
|
Packit |
1470ea |
GNOME’s infrastructure is built to handle with documentation written using
|
|
Packit |
1470ea |
gtk-doc.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="build-system">
|
|
Packit |
1470ea |
<title>Build System</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
To integrate gtk-doc into a project’s build system, follow the
|
|
Packit |
1470ea |
<link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">
|
|
Packit |
1470ea |
instructions in the gtk-doc manual</link>. Note that while the
|
|
Packit |
1470ea |
<file>sections.txt</file> file is automatically generated the first time
|
|
Packit |
1470ea |
gtk-doc is run, it is not generated subsequently, and should be kept up to
|
|
Packit |
1470ea |
date manually. It should also be
|
|
Packit |
1470ea |
<link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">
|
|
Packit |
1470ea |
in version control</link>.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
gtk-doc’s no-tmpl flavour should be used, and XML mode should
|
|
Packit |
1470ea |
be used instead of SGML. (tmpl mode and SGML are both outdated and slower
|
|
Packit |
1470ea |
than XML.)
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
FIXME: This should be updated once
|
|
Packit |
1470ea |
https://bugzilla.gnome.org/show_bug.cgi?id=743182 lands.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
If the package version is needed to be substituted into the documentation,
|
|
Packit |
1470ea |
create a file named <file>docs/version.xml.in</file>, containing:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
@PACKAGE_VERSION@
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Add it to AC_CONFIG_FILES in <file>configure.ac</file>, then
|
|
Packit |
1470ea |
include it into the main documentation file (<file>*-docs.xml</file>)
|
|
Packit |
1470ea |
using: <!ENTITY version SYSTEM "version.xml"> in the
|
|
Packit |
1470ea |
DOCTYPE at the top of the document. The package version can
|
|
Packit |
1470ea |
then be used inline as &version; .
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="standard-layout">
|
|
Packit |
1470ea |
<title>Standard Layout</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Using a standard layout for the table of contents, sections, appendices,
|
|
Packit |
1470ea |
etc. means the same <file>project-name-docs.xml</file> template
|
|
Packit |
1470ea |
can be reused with few changes between projects. It also means the
|
|
Packit |
1470ea |
documentation layout is similar across all projects, making it more
|
|
Packit |
1470ea |
familiar to developers.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The following layout is suggested:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<listing>
|
|
Packit |
1470ea |
<title><file>project-name-docs.xml</file></title>
|
|
Packit |
1470ea |
<desc>A template top-level gtk-doc file for a project</desc>
|
|
Packit |
1470ea |
<xi:include href="example-docs.xml" parse="text" />
|
|
Packit |
1470ea |
</listing>
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="licensing">
|
|
Packit |
1470ea |
<title>Licensing</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
FIXME: Update this once
|
|
Packit |
1470ea |
https://bugzilla.gnome.org/show_bug.cgi?id=742580 is fixed.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
It is important to make the license used for API references clear,
|
|
Packit |
1470ea |
especially if they contain code examples which could be copied around.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Typically, projects use the same license for their API reference as for
|
|
Packit |
1470ea |
the project’s code itself, to avoid confusion. Some other projects use
|
|
Packit |
1470ea |
CC-BY-SA 3.0 for all their reference documentation. The choice is yours.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
As shown in the <link xref="#standard-layout">Standard Layout</link> you
|
|
Packit |
1470ea |
should include a <file>license.xml</file> in the top-level gtk-doc DocBook
|
|
Packit |
1470ea |
file which gives the full text of your documentation license.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="public-api">
|
|
Packit |
1470ea |
<title>Public APIs</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
All public APIs must have gtk-doc comments. For functions, these should
|
|
Packit |
1470ea |
be placed in the source file, directly above the function.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
/**
|
|
Packit |
1470ea |
* gtk_get_flow:
|
|
Packit |
1470ea |
* @widget: a #GtkWidget
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Gets the flow of a widget.
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Note that flows may be laminar or turbulent...
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Returns: (transfer none): the flow of @widget
|
|
Packit |
1470ea |
*/
|
|
Packit |
1470ea |
GtkFlow *
|
|
Packit |
1470ea |
gtk_get_flow (GtkWidget *widget)
|
|
Packit |
1470ea |
{
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
...
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
}
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Documentation comments for macros, function types, class
|
|
Packit |
1470ea |
structs, etc. should be placed next to the definitions, typically
|
|
Packit |
1470ea |
in header files.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Section introductions should be placed in the source file they describe,
|
|
Packit |
1470ea |
after the license header:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
/**
|
|
Packit |
1470ea |
* SECTION:gtksizerequest
|
|
Packit |
1470ea |
* @Short_Description: Height-for-width geometry management
|
|
Packit |
1470ea |
* @Title: GtkSizeRequest
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* The GtkSizeRequest interface is GTK+'s height-for-width (and
|
|
Packit |
1470ea |
* width-for-height) geometry management system.
|
|
Packit |
1470ea |
* ...
|
|
Packit |
1470ea |
*/
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Keep in mind that in order to include a function, macro,
|
|
Packit |
1470ea |
function type, or struct type, it needs to be listed in your
|
|
Packit |
1470ea |
documentation’s <file>modulename-sections.txt</file> file.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
To properly document a new class, it needs to be given its own
|
|
Packit |
1470ea |
section in <file>modulename-sections.txt</file>, needs to be
|
|
Packit |
1470ea |
included in your toplevel <file>modulename-docs.sgml</file>,
|
|
Packit |
1470ea |
and the get_type() function for your class needs
|
|
Packit |
1470ea |
to be listed in your <file>modulename.types</file>.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="introspection-annotations">
|
|
Packit |
1470ea |
<title>Introspection Annotations</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Each gtk-doc comment should have appropriate
|
|
Packit |
1470ea |
<link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">
|
|
Packit |
1470ea |
GObject introspection annotations</link>. These are useful for two
|
|
Packit |
1470ea |
reasons:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list type="numbered">
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
They add important information about parameter types, nullability and
|
|
Packit |
1470ea |
memory management to the C API documentation generated by gtk-doc.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
They allow public APIs to be automatically bound in other languages,
|
|
Packit |
1470ea |
such as Python or JavaScript.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Introspection annotations add information to APIs (functions, function
|
|
Packit |
1470ea |
parameters, function return values, structures, GObject properties,
|
|
Packit |
1470ea |
GObject signals) which is otherwise not present in the machine readable C
|
|
Packit |
1470ea |
API and only exists in the form of human readable documentation or
|
|
Packit |
1470ea |
convention. They are very important.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
In gtk-doc comments, annotations should be preferred over human-readable
|
|
Packit |
1470ea |
equivalents. For example, when documenting a function parameter which may
|
|
Packit |
1470ea |
be NULL , use the (nullable) annotation rather
|
|
Packit |
1470ea |
than some text:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
/**
|
|
Packit |
1470ea |
* my_function:
|
|
Packit |
1470ea |
* @parameter: (nullable): some parameter which affects something
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Body of the function documentation.
|
|
Packit |
1470ea |
*/
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Instead of:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
/**
|
|
Packit |
1470ea |
* my_bad_function:
|
|
Packit |
1470ea |
* @parameter: some parameter which affects something, or %NULL to ignore
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Bad body of the function documentation.
|
|
Packit |
1470ea |
*/
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
For more information on introspection, see the
|
|
Packit |
1470ea |
<link xref="introspection">introspection guidelines</link>.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="symbol-versioning">
|
|
Packit |
1470ea |
<title>Symbol Versioning</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Whenever a symbol is added to the public API, it should have a
|
|
Packit |
1470ea |
documentation comment added. This comment should always contain a
|
|
Packit |
1470ea |
Since line with the package version number of the release
|
|
Packit |
1470ea |
which will first contain the new API. This should be the number currently
|
|
Packit |
1470ea |
in <file>configure.ac</file> if
|
|
Packit |
1470ea |
<link xref="versioning#release-process">post-release version
|
|
Packit |
1470ea |
incrementing</link> is being used.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
For example:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
/**
|
|
Packit |
1470ea |
* my_function:
|
|
Packit |
1470ea |
* @param: some parameter
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Body of the function documentation.
|
|
Packit |
1470ea |
*
|
|
Packit |
1470ea |
* Since: 0.5.0
|
|
Packit |
1470ea |
*/
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
gtk-doc uses this information to generate indexes of the APIs added in
|
|
Packit |
1470ea |
each release. These should be added to the main <file>*-docs.xml</file> as
|
|
Packit |
1470ea |
an appendix:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<title>Appendices</title>
|
|
Packit |
1470ea |
<index id="api-index-full">
|
|
Packit |
1470ea |
<title>API Index</title>
|
|
Packit |
1470ea |
<xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include>
|
|
Packit |
1470ea |
</index>
|
|
Packit |
1470ea |
<index id="api-index-deprecated">
|
|
Packit |
1470ea |
<title>Index of deprecated symbols</title>
|
|
Packit |
1470ea |
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include>
|
|
Packit |
1470ea |
</index>
|
|
Packit |
1470ea |
<index role="0.1.0">
|
|
Packit |
1470ea |
<title>Index of new symbols in 0.1.0</title>
|
|
Packit |
1470ea |
<xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include>
|
|
Packit |
1470ea |
</index>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
|
|
Packit |
1470ea |
</part>]]>
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="dbus-api">
|
|
Packit |
1470ea |
<title>D-Bus APIs</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
D-Bus interface descriptions contain documentation comments, and these can
|
|
Packit |
1470ea |
be extracted from the XML using <cmd>gdbus-codegen</cmd>, and turned into
|
|
Packit |
1470ea |
DocBook files to be included by gtk-doc.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
FIXME: Create a page on D-Bus and link to it. Put automake rules to
|
|
Packit |
1470ea |
generate the documentation somewhere.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</comment>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The DocBook files can be included in the main <file>*-docs.xml</file> file
|
|
Packit |
1470ea |
using:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<title>C Interfaces</title>
|
|
Packit |
1470ea |
<partintro>
|
|
Packit |
1470ea |
<para>C wrappers for the D-Bus interfaces.</para>
|
|
Packit |
1470ea |
</partintro>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<xi:include href="xml/SomeDBusService.xml"/>
|
|
Packit |
1470ea |
<xi:include href="xml/SomeOtherService.xml"/>
|
|
Packit |
1470ea |
</chapter>]]>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The generated XML files must be included in the content_files
|
|
Packit |
1470ea |
variable in your gtk-doc <file>Makefile.am</file>, otherwise the build
|
|
Packit |
1470ea |
will fail. (This is to fix situations where the builddir does
|
|
Packit |
1470ea |
not equal the srcdir .)
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="keeping-up-to-date">
|
|
Packit |
1470ea |
<title>Keeping Documentation Up to Date</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
gtk-doc comes with support for checking the documentation with some basic
|
|
Packit |
1470ea |
tests. These check that all version indexes are included in the main
|
|
Packit |
1470ea |
<file>*-docs.xml</file> file and that all symbols are documented, among
|
|
Packit |
1470ea |
other things.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
These tests should always be enabled, by adding the following to your
|
|
Packit |
1470ea |
gtk-doc <file>Makefile.am</file>:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
TESTS = $(GTKDOC_CHECK)
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
They will then be run as part of <cmd>make check</cmd>.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
</page>
|