gnome-doc1

Usage

Overview

gnome-doc This will read a 'c' file and scan for embedded comments in the style of gnome comments (+minor extensions - see below).

All output goes to stdout, with errors to stderr.

Options

-docbook -html -text -man

Set output format using one of -docbook -html -text or -man. Default is man.

-function

If set, then only generate documentation for the given function(s). All other functions are ignored.

c files

list of 'c' files to process

Format of comments

In the following table,
		(...)? signifies optional structure.
		(...)* signifies 0 or more structure elements.
        /**
	 * function_name(:)? (- short description)?
	 * @parameterx: (description of parameter x)?)*
	(* a blank line)?
	 * (Description:)? (Description of function)?
	 * (section header: (section description)? )*
	(*)?*/
      So .. the trivial example would be:
      /**
       * my_function
       **/
      If the Description: header tag is omitted, then there must be a blank
      line after the last parameter specification.
       e.g.
	/**
	 * my_function - does my stuff
	 * @my_arg: its mine damnit
	 *
	 * Does my stuff explained. 
	 */
	or, could also use:
	/**
	 * my_function - does my stuff
	 * @my_arg: its mine damnit
	 * Description: Does my stuff explained. 
	 */
	etc.
	All descriptions can be multiline, apart from the short function
	description.
	All descriptive text is further processed, scanning for the
	following special patterns, which are highlighted appropriately.
	funcname()  - function
	$ENVVAR     - environmental variable
	struct_name - name of a structure
	@parameter  - name of a parameter
	%CONST      - name of a constant.