I can't tell the difference between Whizzo butter and this dead crab. (MPFC 1)
All Yagdoc features are described in the present tense, although some may be implemented only partially or not at all at the time you are reading this.
Gtk-Doc | Yagdoc |
---|---|
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. |
Gtk-Doc | Yagdoc |
---|---|
Two possible documentation sources exist:
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:
Tools that facilitate creation and updates of these source code comments are provided. |
Gtk-Doc | Yagdoc |
---|---|
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. |
Gtk-Doc | Yagdoc |
---|---|
Parameters and fields ( The canonical form of function return value field is Traits, i.e. non-symbol fields ( 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 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 ( The canonical form of function return value field is Traits, i.e. non-symbol fields, are written
Nested symbols are written
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 Signal argument types can be overriden with
|