Valadoc - Documentation Tool for the Vala Project
Introduction
valadoc is a command line tool that generates Vala programming documentation from a library's API (Application Programming Interface).
The library's API can be written manually in a VAPI file or generated automatically from source files and held in a GIR (GObject Introspection Repository) file. valadoc can generate documentation from both a VAPI file or a GIR file.
If the library is written in Vala then valadoc can generate the documentation from the library's Vala source files.
Documentation Comments
Documentation comments are relevant to VAPIs and Vala source files. GIR files are XML files and can include documentation elements, but do not have documentation comments added to them.
Documentation comments are placed in a VAPI or Vala source file above the symbol to be documented. A documentation comment is of the form:
/**
* Brief description of symbol
*
* Optional long description of symbol
*
* Optional taglets, for example:
* @param parameter_name Description of this parameter of a function
*/
Note the double asterisk at the beginning of the comment. This denotes a documentation comment and is then picked up by Valadoc.
See Valadoc Comment Markup for more details.
Valadoc extracts the comments from the source files and combines them in to API documentation. When no comments are present Valadoc will only extract the symbols to use in the documentation.
Plans:
- gtk-doc-Translation (C-Code+gtk-doc comments)
- Vala code-attributes
Download
Since Vala 0.38.0 Valadoc has been included in the mainline repository for Vala.
Development is going on at https://gitlab.gnome.org/GNOME/vala.
Download the repository using:
git clone https://gitlab.gnome.org/GNOME/vala.git
Requirements
See also
Contact
Development needs and bug reports can be raised in the Vala Projects's issue tracker. Merge requests are also welcome.