In order to make the task of extracting the functional headers easier, we could follow one of the numerous commenting styles available (javadoc, linuxdoc, kernel etc..). Here is a brief description of commenting in the kernel style.

In the following listing, (...)? 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 ommitted, then there must be a blank line after the last parameter specification. For example:

  /**
   * my_function - does my stuff
   * @my_arg: its mine damnit
   *
   * Does my stuff explained. 
   */

or, Description: can also be used, this way:

  /**
   * my_function - does my stuff
   * @my_arg: its mine damnit
   * Description: Does my stuff explained. 
   */

Beside functions you can also write documentation for structs, unions, enums and typedefs. Instead of the function name you must write the name of the declaration; the struct/union/enum/typedef must always precede the name. Nesting of declarations is not supported.

Use the argument mechanism to document members or constants. For example:

  /**
   * struct my_struct - short description
   * @a: first member
   * @b: second member
   * 
   * Longer description
   */
  struct my_struct {
      int a;
      int b;
  };

All descriptions can be multiline, except the short function description.

You can also add additional sections. The Context: of the function, e.g. whether the functions can be called from interrupts etc. can be explained by adding a section. Unlike other sections you can end it with an empty line.

Example-sections should contain the string EXAMPLE so that they are marked appropriately in DocBook.

  /**
   * user_function - function that can only be called in user context
   * @a: some argument
   * Context: !in_interrupt()
   * 
   * Some description
   * Example:
   *    user_function(22);
   */
  ...

All descriptive text is further processed, scanning for the following special patterns, which are highlighted appropriately. These patterns can be used anywhere in short/long descriptions. They are appropriately formatted.

  /**
   *   db_sketch_bspline - Sketches a bspline curve on the drawing board.
   *   @db_plane: Initiated drawing board plane.
   *
   *   Description: This function draws a bspline curve (with preset parameters)
   *                on a given drawing board. Should be used for illustration purpose
   *                only.
   *
   *   Example:
   *	  board_t* myboard;
   *       ...  
   *      // Draw a spline on the board
   *      if (db_sketch_bspline(myboard) == FAIL) { // Handle error
   *      }
   *
   *   Returns: SUCCESS in case of a successfull paint, FAIL otherwise.
   *
   *   See Also: 
   *     db_sketch_beizer()
   */
  int db_sketch_bspline (board_t* plane)
  {
     .... 
     return sketch_status;
  }