libs-base/Documentation/manual/GSDoc.texi

@paragraphindent 0

@node GSDoc
@appendix The GNUstep Documentation System
@cindex gsdoc

GNUstep includes its own documentation system for producing HTML, PDF, and
other readable documents for developers and users.  (It also includes
facilities for ``Help'' accessed within applications, but these are not
covered here.)  It is based on @i{GSdoc}, an XML language designed
specifically for writing documentation for the @uref{http://www.gnustep.org,
GNUstep project}.  In practice, that means that it is designed for writing
about software, and in particular, for writing about Objective-C classes.

It may be used to write narrative documentation by hand, and it can also be
autogenerated by the @i{autogsdoc} tool, which parses Objective-C source
files and documents classes, methods, functions, macros, and variables found
therein, picking up on special comments when provided to enhance the
documentation.

You can read more about GSdoc itself in this
@uref{../../Tools/Reference/gsdoc.html, document}.

The @i{autogsdoc} tool is described
@uref{../../Tools/Reference/autogsdoc.html, here}.

(Both of these documents are part of the
@uref{../../Tools/Reference/index.html, Base Tools} documentation.)


@section Quick Start

The basic approach to using GSdoc is this: when writing source code, put
comments that begin with ``@code{/**}'' instead of the usual C ``@code{/*}''
in your @code{@@interface} or @code{@@implementation} file above class,
variable, and method declarations.  If you have any functions or macros you
are making available put such comments in front of them too.  The comments
still end with the regular ``@code{*/}'', no ``@code{**/}'' is necessary.

@example
/**
 *  The point class represents 2-d locations independently of any graphical
 *  representation.
 */
@@interface Point : NSObject
@{
    // instance variables ...
@}

/**
 *  New point at 0,0.
 */
+ new;

 // ...

/**
 *  Return point's current X position.
 */
- (float) x;
 // ...
@@end
@end example

When you are finished, invoke @i{autogsdoc} giving it the names of all
your header files.  (It will find the implementation files automatically, as
long as they have the same names; alternatively, give it the names of the
implementation files as well.)  This will produce a set of HTML files
describing your classes.  If you include the '@code{-MakeFrames YES}'
argument, the HTML will be structured into frames for easy navigation.

(Autogsdoc, like all GNUstep command line tools, is found in the
$@{GNUSTEP_SYSTEM_ROOT@}/Tools directory.)

You can also generate documentation automatically using the GNUstep make
utility.  Consult its primary @uref{../../Make/Manual/make_toc.html,
documentation} for details.  The short story is:

@example
include $(GNUSTEP_MAKEFILES)/common.make

DOCUMENT_NAME = MyProject

MyProject_AGSDOC_FILES = <space-separated list of header files>
MyProject_AGSDOC_FLAGS = <flags, like MakeFrames YES>

include $(GNUSTEP_MAKEFILES)/documentation.make
@end example

Usually this is put into a separate makefile called ``@code{DocMakeFile}'' in
the source directory.


@section Cross-Referencing

GSdoc provides the ability to reference entities both within the project and
in external projects.  When writing GSdoc comments in source code, references
are particularly easy to create.  To refer to an argument of the method or
function you are documenting, just type it normally; it will be presented in a
special type face in the final documentation to show it is an argument.  To
refer to another method within the same class you are documenting, just type
its selector with the + or - sign in front.  This will be converted into a
hyperlink in output forms that support that.  To refer to another class, you
just type the class's name in [Brackets].  To refer to a method in another
class, put the method selector after the name, as in
[Class-methodWithArg1:andArg2:] (do not include a space).  To refer to a
protocol, use [(BracketsAndParentheses)] instead of just brackets.  To refer
to a category, use [Class(Category)].  For methods in these two cases, put the
method name outside the parentheses.  To refer to a function, simply type its
name suffixed by parentheses().


@section Comment the Interface or the Implementation?

Since @code{autogsdoc} picks up comments both from interface/header files and
implementation/source files, you might be wondering where it is best to put
them.  There is no consensus on this issue.  If you put them in the interface,
then anyone you distribute your library to (with the headers but not the
source) will be able to generate the documentation.  The header file carries
all of the specification for the class's behavior.  On the other hand, if you
put the comments in the implementation, then people editing the source code
will have the method descriptions handy when they need them.  If @i{autogsdoc}
finds comments for the same entity in both interface and implementation, they
are concatenated in the result.

Nonetheless, the recommendation of this author is that you put the comments
in the header, since this is more within the spirit of Objective-C, where the
interface file declares the behavior of a class.

@section Comparison with OS X Header Doc and Java JavaDoc

The HTML output from all of these systems is roughly comparable.  In terms of
and comments needed in the source code to produce good class documentation,
the GSdoc / autogsdoc system aims for maximal simplicity.  In practice,
requiring lots of special formatting makes developers less likely to document
things, therefore, as described above, GSdoc does not require it, letting the
parser do the work instead of the person.

In terms of non-HTML output formats and control over the HTML format, these
are not provided with GSdoc, yet, but there are plans to provide them through
the use of XSLT as a presentation layer.

@page