Autogsdoc... a tool to make documentation from source code


Richard Frith-Macdonald (richard@brainstorm.co.uk)

Copyright: (C) 2001 Free Software Foundation, Inc.

Contents -

  1. The autogsdoc tool
  2. Overview
  3. Source Code Markup
  4. Extra markup
  5. Method markup
  6. Automated markup
  7. Arguments and Defaults
  8. Inter-document linkage
  9. Implementation Notes

The autogsdoc tool


The autogsdoc tool is a command-line utility that helps developers produce reference documentation for GNUstep APIs. It also enables developers to write and maintain other documentation in XML and have it converted to HTML. In detail, autogsdoc will:

synopsis: autogsdoc (options) (files)
    (options) described below
    (files) .h, .m, .gsdoc, and/or .html files, in any order.

The most common usage this is to run the command with one or more header file names as arguments... the tool will automatically parse corresponding source files in the same directory as the headers (or the current directory, or the directory specified using the DocumentationDirectory default), and produce GSDoc and HTML files as output. For best results this mode should be run from the directory containing the source files.

GSDoc files may also be given directly in addition or by themselves, and will be converted to HTML. See the GSDoc reference for information on the GSDoc format.

Finally, HTML files may be given on the command line. Cross-references to other parts of code documentation found within them will be rewritten based on what is found in the project currently.

Source Code Markup

The source code parser will automatically produce GSDoc documents listing the methods in the classes found in the source files, and it will include text from specially formatted comments from the source files.

Any comment beginning with slash and two asterisks rather than the common slash and single asterisk, is taken to be GSDoc markup, to be use as the description of the class or method following it. This comment text is reformatted and then inserted into the output.
Where multiple comments are associated with the same item, they are joined together with a line break (<br />) between each if necessary.
Within a comment the special markup <ignore> and </ignore> may be used to tell autogsdoc to completely ignore the sourcecode between these two pieces of markup (ie. the parser will skip from the point just before it is told to start ignoring, to just after the point where it is told to stop (or end of file if that occurs first).

The tool can easily be used to document programs as well as libraries, simply by giving it the name of the source file containing the main() function of the program - it takes the special comments from that function and handles them specially, inserting them as a section at the end of the first chapter of the document (it creates the first chapter if necessary).

Options are described in the section Arguments and Defaults below.

Extra markup

There are some cases where special extra processing is performed, predominantly in the first comment found in the source file, from which various chunks of GSDoc markup may be extracted and placed into appropriate locations in the output document -

NB The markup just described may be used within class, category, or protocol documentation ... if so, it is extracted and wrapped round the rest of the documentation for the class as the class's chapter. The rest of the class documentation is normally inserted at the end of the chapter, but may instead be substituted in in place of the <unit /> pseudo-element within the <chapter> element.

Method markup

In comments being used to provide text for a method description, the following markup is removed from the text and handled specially -

Automated markup

Generally, the text in comments is reformatted to standardise and indent it nicely... the reformatting is not performed on any text inside an <example> element.
When the text is reformatted, it is broken into whitespace separated 'words' which are then subjected to some extra processing...

Arguments and Defaults

The tool accepts certain user defaults (which can of course be supplied as command-line arguments by prepending '-' before the default name and giving the value afterwards, as in - Clean YES):

Inter-document linkage

The 'Up' default is used to specify the name of a document which should be used as the 'up' link for any other documents used.
This name must not include a path or extension.
Generally, the document referred to by this default should be a hand-edited GSDoc document which should have a back section containing a project index. e.g.

  <?xml version="1.0"?>
  <!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN"
  <gsdoc base="index">
      <title>My project reference</title>
      <author name="my name"></author>
        <heading>My project reference</heading>
        <index scope="project" type="title" />

Implementation Notes

The autogsdoc tool internally makes use of the following four classes-

Parses source code comments to an internal representation.
Converts internal representation of source comments to a gsdoc document.
Internal representation of an igsdoc file, representing indices of a project's files.
Converts gsdoc XML to HTML, using AGSIndex instances.
Title Index