ObjcDoc - Objective-C documentation tool
ObjcDoc is a tool designed to aid programmers in documenting Objective-C class libraries. It can parse Objective-C source code (both include and implementation files) and will create HTML output files containing class documentation extracted from special comments inside the source code.
Additionally, ObjcDoc can also create a class and protocol index and a view of the complete class inheritance hierarchy with links to the individual documentation files.
Each non-option argument on the command line may either be an Objective-C include (`*.h') or implementation file (`*.m') or the name of a directory, which is then searched for source code files (recursively). All files collected in this way are scanned for public class and protocol declarations.
For every class found, ObjcDoc will create two output files containing hypertext documentation for this class, its instance variables and its class and instance methods. Also included are links to all direct subclasses and implemented protocols. If a methods is re-implemented in a subclass, a link to the implementation in the base class is provided (if documentation for this exists). Methods from categories are incorporated into the documentation for the class they augment, grouped by category name.
ObjcDoc currently supports the following options:
-x or
--exclude options) that should not be documented. Equivalent to using
`@nodoc' in the class comment (see Magic Section Keywords).
html', which is the default.
html'),
which can be used to emulate a simple class browser. Some authors consider
the use of frames bad style, so this feature is turned off by default. This
option also implies --tree, since the inheritance hierarchy is displayed
in the initial frameset.
--nosrc option, of
course.
--index and --tree
options, if these have been specified.
--resolve options are allowed.
ObjcDoc can parse two different kinds of input files: Objective-C header (i.e. include) files and Objective-C implementation files. It does not impose any restrictions on the contents of these files, but it will only recognize and extract documentation from comments in these files if they appear ``in the right places''. All comment text is assumed to be ISO 8859-1 (``Latin-1'') encoded (this matters only if non-ASCII characters appear inside), which is also the default encoding of HTML documents. Character entities may be used to represent other Unicode characters.
Comments for documented classes, categories or protocols must be placed as
a single comment block immediately before (or on the same line after)
the corresponding `@interface', `@implementation' or `@protocol'
line. Empty lines between comment block and declaration are always ignored.
A short description for individual instance variables and class or instance methods should precede each variable or method declaration, respectively, as a single comment block. Alternatively, a single-line comment may be appended to the declaration on the same line (see the examples below).
Methods may be grouped together into ``categories'' (just sets of methods, not Objective-C categories) by grouping them in the interface or protocol declaration and preceding them with a separate comment block for this group. A group lasts until the next group begins or there are no more methods in this interface.
Longer documentation texts for each method should be included in the implementation files for the corresponding classes. These can be used to describe how the method can be used, its parameters, return value, exceptions etc. Again, this must be placed as a single comment block per method immediately before the method implementation. If a method overrides an implementation in another class, but does not provide a comment block of its own, the corresponding comment from the base class is used.
ObjcDoc (unlike Javadoc) does not require the use of a special comment type and will accept a wide range of different comment styles. For example, all of the following are exactly equivalent:
/*
* Validate internal state.
*/
- (BOOL) isValid;
/*
Validate internal state.
*/
- (BOOL) isValid;
//
// Validate internal state.
//
- (BOOL) isValid;
- (BOOL) isValid; /* Validate internal state. */
- (BOOL) isValid; // Validate internal state.
Each of the above would be treated as a single comment block. A comment appended to a code fragment on the same line is internally treated just as if it appeared immediately before the code fragment on its own line.
A comment block is defined as:
However, if you place a comment after a declaration on the same line, as shown in the last two examples above, there is no way to extend this comment block across multiple lines. (well, almost: You can use the line continuation feature of ANSI-C to join multiple source code lines into a single logical line.)
All types of comments mentioned above may contain any number of the keywords listed here to add (inline) hypertext links. If the output format does not support links, text is inserted instead.
+' or
`-' (though this is optional after `#') to distinguish between class
and instance methods.
+' if it refers to a class method (and can optionally be
preceded by `-' if it refers to an instance method).
The following keywords can be used to add pre-defined sections to the generated documentation (typically a method documentation). Section keywords should only appear at the start of a comment line, and consume all text until the end of the current (logical) line.
If the text for a section keywords needs to span multiple input lines,
you have to add line continuation characters to all but the last line
(see the example for `\newline' under Special Characters).
@param' keywords are allowed (one per parameter).
@raises' or `@throws' keywords are allowed.
@see' keywords are allowed.
These technically also count as section keywords, but are interpreted in a different way:
< and >) must be left unescaped,
since this is handled automatically.
All comments mentioned above may contain text marked by the characters listed below to change the visible appearance or interpretation of the text:
|', which can be escaped) in
a fixed width font, if possible.
* [...] * @param foobar This is a very long \ * parameter description. * [...]
If all of this is not enough, HTML tags may be embedded directly into
the comment text to add images, lists or other effects. Note that for
this reason, the characters &, < and > always need to
be escaped unless you want to write HTML tags or character entities.
/*
* Send the current selector to the target. The action
* will pass the /sender/ object, /count/ arguments from
* the argument array starting at /args/ and the user data
* (if it has been set) to the method. The return value
* will be stored in args[count], which must contain the
* correct type information for the return value.
* <p>
* If the selector's return type is |void| and /count/ is
* |0|, args may be |NULL|.
* <p>
* Note:!! The current implementation will only pass up to
* 6 arguments from the /args/ array. If it contains more
* values, the argument list will be truncated.
*
* @see @GTK#-connectSignal:withAction: in @class(GTK)
*/
- (void) performWithSender:(id) sender args:(GtkArg *) args
count:(unsigned) count
{
[...]
}
Output format selection (-f) is only partly implemented.
Empty lines within comments should be recognized as paragraph breaks
(insert `<p>'), unless they are part of example code.
It may be useful to select an input file encoding other than ISO 8859-1, but translating different character sets is a non-trivial task.
As you might have guessed, this program was inspired by the Javadoc tool included in the Java Development Kit, which can be used to create documentation for Java classes. ObjcDoc tries to provide equivalent functionality to Objective-C developers.
The current version (3.0) is the result of a complete rewrite and - though functionally equivalent and mostly compatible - internally bears almost no resemblance to ObjcDoc 2.x.
javadoc(1), ocdoc(1)
Holger Ludwig, Elmar Ludwig < elmar@informatik.uni-osnabrueck.de >