Writing documentation

GNUstep documentation is produced by a variety of methods, but the main class reference documentation (i.e. the stuff you are concerned with if you are implementing new library code) is generated automatically from the Objective-C header files.

The gnustep-make system supports automatic generation of documentation, and the gnustep-base library includes the autogsdoc tool used to produce the documentation. Autogsdoc is similar tools like Doxygen or Javadoc, but was written before these tools were generally available and was designed specifically for Objective-C documentation. it has the advantages of (relative) simplicity and no external dependencies ... if you have gnustep-base installed then you have the ability to generate GNUstep documentation.

Basically, to provide documentation for a class, you place a comment immediately before the class in the header file, and start the comment with an extra asterisk ('/**' rather than '/*') to tell autogsdoc that the comment is part of the documentation.

To provide documentation for an individual method, you place a comment immediately before the declaration of that method in the header.

The autogsdoc tool takes the content of the comments an produces an intermediate XML representation which is then converted to HTML. You can thereof use familiar markup like
to force a line break in the documentation, but you must also be careful to escape < and & characters using 'lt' and 'amp' in your comments if you do not want them to be treated as markup.

Autogsdoc also handles automatic cross referencing and formatting to a large extent, but the full details are beyond the scope of a small wikipedia article ... you should look at the autogsdoc documentation and the gsdoc markup language documentation for full information.

What do you need to document? Well, for each class or protocol you should provide an overview of what that class or protocol is intended to be used for, and should ideally provide example use cases and simple example code. For each method in the class you should provide a description of what the method does, what effect different arguments have, what possible return values are, and what exceptions might be raised (if any).

What you don't need to do is provide information about API versioning in the comments ... there are macros you should use in the header to define visibility of methods in different versions of the API, and autogsdoc should detect those automatically and insert information into the documentation to tell the reader which versions of the API the method is present in.

---

See also

• autogsdoc documentation
• autogsdoc man page