What is GtkDoc ?
GtkDoc is a tool used to extract API documentation from C-code like Doxygen, but handles documentation of GObject (including signals and properties) that makes it very suitable for GTK+ apps and libraries. It uses docbook for intermediate files and can produce html by default and pdf/man-pages with some extra work.
I propose a DocumentationProject/GtkDocGnomeGoal to improve the current API docs.
Git repository
The project is hosted on GNOME's GitLab.
You can check out the current development snapshot using
git clone https://gitlab.gnome.org/GNOME/gtk-doc.git
Contact
- IRC: #gtkdoc at irc.gnome.org
GtkDoc Documentation
GtkDoc has a manual you can see here: https://developer-old.gnome.org/gtk-doc-manual/stable/
You can also download the source code and open gtk-doc/help/manual/C/gtk-doc-manual.xml with yelp directly. From a terminal, type:
yelp file:///absolute/path/to/gtk-doc/help/manual/C/gtk-doc-manual.xml
Building documentation using GtkDoc
Next chapter has the basics for quick reference.
Build Structure
Consider you are building your documentation in doc/ or, if you have different types of documentation (manual, tutorial, various documentation) under doc/reference.
If you have a library composed of different modules, use doc/${MODULE}.
- Create ${MODULES}.types
- include header files that contain GObjects declaration.
edit Makefile.am and complete INCLUDES and GTKDOC_LIBS in order to compile the object scanner. Here is an example for GnomeScan :
INCLUDES= \
-I$(top_srcdir) \
-I$(top_srcdir)/libgnomescan \
-I$(top_srcdir)/libgnomescanui \
-I$(top_builddir) \
$(GNOMESCAN_CFLAGS)
GTKDOC_LIBS= \
$(GNOMESCAN_LIBS) \
$(INTLLIBS) \
-lsane \
$(top_builddir)/libgnomescan/.libs/libgnomescan.la \
$(top_builddir)/libgnomescanui/.libs/libgnomescanui.lamake clean && make to update the documentation.
If you are using a source code management system you should only put the files you change under revision control; usually, this means:
- ${MODULE}-docs.sgml
- ${MODULE}-sections.txt
- Makefile.am
- the templates under tmpl/, if edited manually
You should consider not using the template files under tmpl/: gtk-doc can generate most of the documentation from the source code, including the sections' short and long description. This keeps the documentation tightly attached to the code it references and reduces the amounts of commits you have to perform.
Refer to the manual for further information.
Building a widget gallery
The widget gallery allows yout to attach a picture to a GObject that will be shown in a gallery and on the top right corner of the corresponding documentation page. For instance, if you are building your documentation in doc/
- Create pictures and put them in doc/images/
- Create doc/gallery.xml, with:
<para role="gallery"> </para>
- Then, for each widget, put a code snippet similar to this inside the para tags:
<link linkend="GnomeFoo"> <inlinegraphic fileref="gnome-foo.png" format="PNG" /> </link>
- Edit doc/Makefile.am . Add gallery.xml to the content_files variable and add each PNG to the HTML_IMAGES variables like this :
HTML_IMAGES= \
$(srcdir)/images/gnome-foo.png
content_files= \
gallery.xml- Edit doc/${MODULE}-docs.sgml and include gallery.xml like this :
<chapter> <title>Widget gallery</title> <xi:include href="gallery.xml"/> </chapter>
make clean && make to update your documentation.
Documenting a section
To document a section of the source code do something like this:
/** * SECTION:foo-widget * @short_description: The best widget, ever * @see_also: #BarWidget, #BazWidget * * #FooWidget is the best widget ever written. It does handle foo, bar and baz. * * #FooWidget is available since 1.0 */
Like the rest of the gtk-doc comments, you can use the docbook markup inside them to enhance the layout.
Remember to use document sections inside the .c source files, to avoid unnecessary recompilations.
Documenting Structs
To document a structure, say your widget subclass, do something like this:
/**
* FooWidget:
* @bar: some #gboolean
*
* This is the best widget, ever.
**/
typedef struct _FooWidget {
/*< private >*/
GtkWidget parent;
/*< public >*/
gboolean bar;
} FooWidget;
Hide private struct fields
Use /*< private >*/ before what you want to hide. Use /*< public >*/ for the reverse behavirour.
Documenting Functions
You can document functions like so, usually in the .c file:
/**
* foo_widget_do_something:
* @foo_widget: some foo
* @bar: some bar
*
* Does something to the @foo_widget.
*
* Returns: %TRUE if the operation succeeded, else %FALSE.
**/
gboolean
foo_widget_do_something(FooWidget *foo_widget,
gint bar)
{
...In case the function has variadic arguments, you should use the @... marker:
/**
* foo_widget_set:
* @foo_widget: a #FooWidget
* @first_bar: the first bar to set
* @...: a %NULL-terminated list of bars
*
* Sets a list of bars
*/
void
foo_widget_set (FooWidget *foo_widget,
const gchar *first_bar,
...)
{
...Return values can be indicated using any of these markers:
@returns:
Returns:
Return value:
the last one is the preferred way for GLib and GTK+, but you can choose any of them for your project - but please, be consistent!
/**
* foo_widget_peek_bar:
* @foo: a #FooWidget
* @bar: the bar to retrieve from @foo
*
* Retrieves a pointer to the value of @bar from a #FooWidget.
*
* Returns: the value of the requested bar, or %NULL.
* The value is owned by the #FooWidget and should never be
* modified or freed
*
* Since: 1.4
*/
G_CONST_RETURN gchar *
foo_widget_peek_bar (FooWidget *foo,
const gchar *bar)
{
...Please remember to:
- Document whether returned objects, lists, strings, etc, should be freed/unrefed/released.
- Document whether parameters can be NULL, and what happens if they are.
- Mention interesting pre-conditions and post-conditions where appropriate.
TODO: Use a more realistic example.
Documenting Properties
You can document GObject properties inline with their initialisation:
/**
* FooWidget:is-cool:
*
* Whether this widget is cool or not.
**/
g_object_class_install_property (object_class,
PROP_IS_COOL,
...
Documenting Signals
You can document GObject signals inline with their parameters and flags, using mostly the same syntax as for a function:
/**
* FooWidget::foobarized:
* @widget: the widget that received the signal
* @foo: some foo
* @bar: some bar
*
* The ::foobarized signal is emitted each time someone tries to foobarize @widget.
**/
foo_signals[FOOBARIZE] =
g_signal_new ("foobarize",
...Please remember to
- Document when the signal is emitted and whether it is emitted before or after other signals.
- Document what an application might do in the signal handler.
Documenting enums
/**
* Something:
* @SOMETHING_FOO: something foo
* @SOMETHING_BAR: something bar
*
* Enum values used for the thing, to specify the thing.
*
**/
typedef enum {
SOMETHING_FOO,
SOMETHING_BAR,
} Something;
Versioning information
You can add versioning information to all documentation elements to tell when an api was introduced, or when it was deprecated, for example:
/**
* foo_get_bar:
* @foo: some foo
* @returns: @foo's bar
*
* Retrieves @foo's bar.
*
* Since: 2.6
*
* Deprecated: 2.12: Use foo_baz_get_bar() instead.
**/
Bar *
foo_get_bar(Foo *foo)
{
...
Linking
To link to an external web page, use <ulink url="link-url">Link Name</ulink>. For instance: <ulink url="http://www.gtk.org/">GTK+</ulink>.
To link to functions, just use the function name followed by braces, for instance: foo_widget_set()
To link objects, structures and enumerations, use the name of the type prefixed with an hash, for instance: #FooWidget. If you want to add a plural form, you should use an XML comment to break the name, for instance: #FooWidget<!-- -->s
To link macros use the symbol prefixed with a percent, for instance: %FOO_IS_WIDGET
The percent symbol should also be used with symbols like NULL, TRUE and FALSE.
To link a section written in a separate sgml file, assign an id to the section and then use <link linkend="sectionid"> in the gtk-doc comment
TODO: Preventing automatic linking.
Further Information
