4
@appendix The GNUstep Documentation System
7
GNUstep includes its own documentation system for producing HTML, PDF, and
8
other readable documents for developers and users. (It also includes
9
facilities for ``Help'' accessed within applications, but these are not
10
covered here.) It is based on @i{GSdoc}, an XML language designed
11
specifically for writing documentation for the @uref{http://www.gnustep.org,
12
GNUstep project}. In practice, that means that it is designed for writing
13
about software, and in particular, for writing about Objective-C classes.
15
It may be used to write narrative documentation by hand, and it can also be
16
autogenerated by the @i{autogsdoc} tool, which parses Objective-C source
17
files and documents classes, methods, functions, macros, and variables found
18
therein, picking up on special comments when provided to enhance the
21
You can read more about GSdoc itself in this
22
@uref{../../Tools/Reference/gsdoc.html, document}.
24
The @i{autogsdoc} tool is described
25
@uref{../../Tools/Reference/autogsdoc.html, here}.
27
(Both of these documents are part of the
28
@uref{../../Tools/Reference/index.html, Base Tools} documentation.)
33
The basic approach to using GSdoc is this: when writing source code, put
34
comments that begin with ``@code{/**}'' instead of the usual C ``@code{/*}''
35
in your @code{@@interface} or @code{@@implementation} file above class,
36
variable, and method declarations. If you have any functions or macros you
37
are making available put such comments in front of them too. The comments
38
still end with the regular ``@code{*/}'', no ``@code{**/}'' is necessary.
42
* The point class represents 2-d locations independently of any graphical
45
@@interface Point : NSObject
47
// instance variables ...
58
* Return point's current X position.
65
When you are finished, invoke @i{autogsdoc} giving it the names of all
66
your header files. (It will find the implementation files automatically, as
67
long as they have the same names; alternatively, give it the names of the
68
implementation files as well.) This will produce a set of HTML files
69
describing your classes. If you include the '@code{-MakeFrames YES}'
70
argument, the HTML will be structured into frames for easy navigation.
72
(Autogsdoc, like all GNUstep command line tools, is found in the
73
$@{GNUSTEP_SYSTEM_ROOT@}/Tools directory.)
75
You can also generate documentation automatically using the GNUstep make
76
utility. Consult its primary @uref{../../Make/Manual/make_toc.html,
77
documentation} for details. The short story is:
80
include $(GNUSTEP_MAKEFILES)/common.make
82
DOCUMENT_NAME = MyProject
84
MyProject_AGSDOC_FILES = <space-separated list of header files>
85
MyProject_AGSDOC_FLAGS = <flags, like MakeFrames YES>
87
include $(GNUSTEP_MAKEFILES)/documentation.make
90
Usually this is put into a separate makefile called ``@code{DocMakeFile}'' in
94
@section Cross-Referencing
96
GSdoc provides the ability to reference entities both within the project and
97
in external projects. When writing GSdoc comments in source code, references
98
are particularly easy to create. To refer to an argument of the method or
99
function you are documenting, just type it normally; it will be presented in a
100
special type face in the final documentation to show it is an argument. To
101
refer to another method within the same class you are documenting, just type
102
its selector with the + or - sign in front. This will be converted into a
103
hyperlink in output forms that support that. To refer to another class, you
104
just type the class's name in [Brackets]. To refer to a method in another
105
class, put the method selector after the name, as in
106
[Class-methodWithArg1:andArg2:] (do not include a space). To refer to a
107
protocol, use [(BracketsAndParentheses)] instead of just brackets. To refer
108
to a category, use [Class(Category)]. For methods in these two cases, put the
109
method name outside the parentheses. To refer to a function, simply type its
110
name suffixed by parentheses().
113
@section Comment the Interface or the Implementation?
115
Since @code{autogsdoc} picks up comments both from interface/header files and
116
implementation/source files, you might be wondering where it is best to put
117
them. There is no consensus on this issue. If you put them in the interface,
118
then anyone you distribute your library to (with the headers but not the
119
source) will be able to generate the documentation. The header file carries
120
all of the specification for the class's behavior. On the other hand, if you
121
put the comments in the implementation, then people editing the source code
122
will have the method descriptions handy when they need them. If @i{autogsdoc}
123
finds comments for the same entity in both interface and implementation, they
124
are concatenated in the result.
126
Nonetheless, the recommendation of this author is that you put the comments
127
in the header, since this is more within the spirit of Objective-C, where the
128
interface file declares the behavior of a class.
130
@section Comparison with OS X Header Doc and Java JavaDoc
132
The HTML output from all of these systems is roughly comparable. In terms of
133
and comments needed in the source code to produce good class documentation,
134
the GSdoc / autogsdoc system aims for maximal simplicity. In practice,
135
requiring lots of special formatting makes developers less likely to document
136
things, therefore, as described above, GSdoc does not require it, letting the
137
parser do the work instead of the person.
139
In terms of non-HTML output formats and control over the HTML format, these
140
are not provided with GSdoc, yet, but there are plans to provide them through
141
the use of XSLT as a presentation layer.
added
removed
Documentation/manual/GSDoc.texi
