Gtk-Doc Comparison

Matches language constructs with regular expressions, ignoring things that don't match.

This approach enables it to simply skip things it does not understand and apparently parse some invalid C such as

typedef enum
{
  G_IO_IN     GLIB_SYSDEF_POLLIN,
  G_IO_OUT    GLIB_SYSDEF_POLLOUT,
  G_IO_PRI    GLIB_SYSDEF_POLLPRI,
  G_IO_ERR    GLIB_SYSDEF_POLLERR,
  G_IO_HUP    GLIB_SYSDEF_POLLHUP,
  G_IO_NVAL   GLIB_SYSDEF_POLLNVAL
} GIOCondition;

On the other hand, it is white space, comment and even and word boundary sensitive, has eternal difficulties understanding recusrive and repetitive structures (with workaround for some common cases crammed in incomprehensible regular expressions).

Failures to recognize a declaration manifest themselves in later stages as unused documentation, partial failures are reported immediately.

Tokenizes source code into tokens and then feeds it to a parser using a simplified C grammar.

This approach enables it to understand nested structures and unions, function arguments that are functions themselves and similar constructs.

struct S {
    struct {
        union {
            int a;
            char b[4];
        } c;
        double d;
    } e;
    void *zoid;
}

On the other hand, it cannot match language constructs “approximately”, either the complete declaration is matched by the simplified grammar, or it is completely rejected.

On the third hand, each failure to parse a declaration is noisy and the user gets an immediate diagnostics.

Two possible documentation sources exist:

• “template” files in the documentation directory, human-written but updated automatically by a tool when the source code changes
• specifically formatted comments in the source code

They can be combined or either of them can be used exclusively (the exclusive use of source code comments is possible only with very recent gtk-doc).

Template files permit to keep the code and documentation separated (whether it is a good thing or not), however, being both human-written and computer-generated makes them prone to versioning (and other) issues.

Only one documentation source exists:

• specifically formatted comments in the source code

Tools that facilitate creation and updates of these source code comments are provided.

Declarations are sorted into documentation sections manually, using so-called section file. Recent versions of gtk-doc also allow to automatically generate this file by putting all declarations from a header file into one section.

Declarations are sorted into documentation sections according to a set of rules matching symbol and header file names. This enables to keep sections automatically updated even if they do not relate to header files 1 : 1 as in these cases the section can be typically determined from the symbol name. The default is the same: to put all declarations from one header file into one section.

Total control freaks can also use a gtk-doc-style section file, which has to be maintained completely manually then.

Parameters and fields (@param:) must come before the description body, i.e. just after symbol name.

The canonical form of function return value field is @Returns:, although many other forms are recognized: @returns:, Return:, Returns:, even bare Returns. Probably the only form not recognized is also the only one that cannot collide with anything: @return:.

Traits, i.e. non-symbol fields (Since, Deprecated, …), are written as Trait:.

Nested symbols are not supported.

Symbol name at the start of documentation block can be optionally followed with a colon.

Header, template/DocBook source and output file names are independent. Section id is set with @section_id in section documentation.

Overrding of generic signal argument names and their types obtained by inspection has to be hardcoded into the program. It is hardcoded for a set of Gtk+ signals and impossible for any other package.

Parameters and fields (@param:) can appear anywhere and therefore description lines must not start with @param:.

The canonical form of function return value field is @return: beacuse return is a C keyword and therefore cannot collide with a parameter name. Some gtk-doc forms are accepted for compatibility, though not the bareword ones.

Traits, i.e. non-symbol fields, are written @:trait:, although several bare gtk-doc traits are accepted for compatibility.

Nested symbols are written @parent/child/…:.

Symbol name at the start of documentation block must be followed with a colon.

DocBook source file name is always equal to its id (and thus to output file name) and is set by sectionizer rules. Most SECTION: names differ from gtk-doc.

Signal argument types can be overriden with @name<override> syntax, their names can be assigned positionally (i.e. order of arguments in the documentation matches the order of signal arguments). Of course, both can be also overriden by extending Inspector class.