2.8. Documentation and Valadoc.org

Valadoc.org is often the first website a Vala developer visits when seeking how to use a binding. A new VAPI commited to Vala Extra VAPIs can be added to Valadoc.org by adding the VAPI to the list of downloaded packages at Valadoc.org and submitting a pull request to the Valadoc.org repository. See the libcolumbus pull request as an example.

Valadoc.org is frequently re-generated. When Valadoc.org is re-generated VAPIs are pulled in from vala-extra-vapis and documentation generated from them. If no documentation comments are associated with a VAPI then Valadoc.org will only show the symbols in the VAPI.

Add a documentation comment before a symbol in the VAPI. A documentation comment is a C multiline comment with an additional asterisk:

 * Brief description of class Foo
 * Long description of class Foo, which can include an example
[CCode (cname = "foo", ref_function = "foo_retain", unref_function = "foo_release")]
public class Foo {
    // Details of binding

The comments can include additional markup. Details are at Valadoc Comment Markup.

The documentation can be generated locally to test how it will appear. First, download and build valadoc:

git clone git://git.gnome.org/valadoc
cd valadoc
make install

Second, generate the documentation:

cd my_binding_directory
valadoc --directory docs --force --package-name mybinding mybinding.vapi

This will generate the HTML documentation in the docs directory. valadoc expects the docs directory to not exist, but --force overrides this. --package-name mybinding will create a sub-directory called mybinding in docs that contains the generated documentation for mybinding.vapi.

The locally generated documentation will have the same structure as valadoc.org, although the visual styling may differ.