1AUTOGSDOC(1) GNUstep System Manual AUTOGSDOC(1)
2
6 autogsdoc - GNUstep API documentation generator and XML->HTML converter
7
10 autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO]
11 [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependen‐
12 cies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-Docu‐
13 mentationDirectory path] [-Declared location] [-Project title] [-Stan‐
14 dards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentIn‐
15 stanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-Con‐
16 stantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate
17 filename] [-TypedefsTemplate filename] [-VariablesTemplate filename]
18 [-SystemProjects string] [-LocalProjects string] [-Projects dictString]
19 [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
20
23 The autogsdoc tool is a command-line utility that helps developers pro‐
24 duce reference documentation for GNUstep APIs. It also enables devel‐
25 opers to write and maintain other documentation in XML and have it con‐
26 verted to HTML. In detail, autogsdoc will:
27 - Extract special comments describing the public interfaces of classes,
29 categories, protocols, functions, and macros from Objective C source
30 code (header files and optionally source files) into GSDoc XML files.
31 - Convert GSDoc XML files, whether generated from source code or writ‐
33 ten manually by developers, into HTML.
34 - Construct indices based on GSDoc XML file sets, and convert those to
36 HTML as well.
37 The most common usage this is to run the command with one or more
40 header file names as arguments ... the tool will automatically parse
41 corresponding source files in the same directory as the headers (or the
42 current directory, or the directory specified using the Documenta‐
43 tionDirectory default), and produce GSDoc and HTML files as output.
44 For best results this mode should be run from the directory containing
45 the source files. (Note that since C is a subset of Objective C, this
46 tool can operate to document functions and other C structures in plain
47 C source.)
48 GSDoc files may also be given directly in addition or by themselves,
50 and will be converted to HTML. See the GSDoc HTML documentation or the
51 gsdoc(7) man page for information on the GSDoc format.
52 Finally, HTML files may be given on the command line. Cross-references
54 to other parts of code documentation found within them will be rewrit‐
55 ten based on what is found in the project currently.
56
59 The source code parser will automatically produce GSDoc documents list‐
60 ing the methods in the classes found in the source files, and it will
61 include text from specially formatted comments from the source files.
62 Any comment beginning with slash and two asterisks rather than the com‐
64 mon slash and single asterisk, is taken to be GSDoc markup, to be use
65 as the description of the class or method following it. This comment
66 text is reformatted and then inserted into the output.
67 Where multiple comments are associated with the same item, they are
68 joined together with a line break (<br/>) between each if necessary.
69 The tool can easily be used to document programs as well as libraries,
71 simply by giving it the name of the source file containing the main()
72 function of the program - it takes the special comments from that func‐
73 tion and handles them specially, inserting them as a section at the end
74 of the first chapter of the document (it creates the first chapter if
75 necessary).
76 Options are described in the section Arguments and Defaults below.
78
81 There are some cases where special extra processing is performed, pre‐
82 dominantly in the first comment found in the source file, from which
83 various chunks of GSDoc markup may be extracted and placed into appro‐
84 priate locations in the output document -
85 AutogsdocSource:
87 In any line where AutogsdocSource: is found, the remainder of the
88 line is taken as a source file name to be used instead of making
89 the assumption that each .h file processed uses a .m file of the
90 same name. You may supply multiple AutogsdocSource: lines where a
91 header file declares items which are defined in multiple source
92 files. If a file name is absolute, it is used just as supplied. If
93 on the other hand, it is a relative path, the software looks for
94 the source file first relative to the location of the header file,
95 and if not found there, relative to the current directory in which
96 autogsdoc is running, and finally relative to the directory speci‐
97 fied by the DocumentationDirectory default.
98 <abstract>
100 An abstract of the content of the document ... placed in the head
101 of the GSDoc output.
102 <author>
104 A description of the author of the code - may be repeated to handle
105 the case where a document has multiple authors. Placed in the head
106 of the GSDoc output. As an aid to readability of the source, some
107 special additional processing is performed related to the document
108 author - Any line of the form 'Author: name <email-address>', or
109 'By: name <email-address>', or 'Author: name' or 'By: name' will be
110 recognised and converted to an author element, possibly containing
111 an email element.
112 <back>
114 Placed in the GSDoc output just before the end of the body of the
115 document - intended to be used for appendices, index etc..
116 <chapter>
118 Placed immediately before any generated class documentation ...
119 intended to be used to provide overall description of how the code
120 being documented works. Any documentation for the main() function
121 of a program is inserted as a section at the end of this chapter.
122 <copy>
124 Copyright of the content of the document ... placed in the head of
125 the GSDoc output. As an aid to readability of the source, some
126 special additional processing is performed - Any line of the form
127 'Copyright (C) text' will be recognised and converted to a copy
128 element.
129 <date>
131 Date of the revision of the document ... placed in the head of the
132 GSDoc output. If this is omitted the tool will try to construct a
133 value from the RCS Date tag (if available).
134 <front>
136 Inserted into the document at the start of the body ... intended to
137 provide for introduction or contents pages etc.
138 <title>
140 Title of the document ... placed in the head of the GSDoc output.
141 If this is omitted the tool will generate a (probably poor) title
142 of its own - so you should include this markup manually.
143 <version>
145 Version identifier of the document ... placed in the head of the
146 GSDoc output. If this is omitted the tool will try to construct a
147 value from the RCS Revision tag (if available).
148 NB The markup just described may be used within class, category, or
150 protocol documentation ... if so, it is extracted and wrapped round the
151 rest of the documentation for the class as the class's chapter. The
152 rest of the class documentation is normally inserted at the end of the
153 chapter, but may instead be substituted in in place of the <unit>
154 pseudo-element within the <chapter> element.
155
158 In comments being used to provide text for a method description, the
159 following markup is removed from the text and handled specially -
160 <init>
162 The method is marked as being the designated initialiser for the
163 class.
164 <override-subclass>
166 The method is marked as being one which subclasses must override
167 (e.g. an abstract method).
168 <override-never>
170 The method is marked as being one which subclasses should NOT over‐
171 ride.
172 <standards>
174 The markup is removed from the description and placed after it in
175 the GSDoc output - so that the method is described as conforming
176 (or not conforming) to the specified standards.
177
180 Generally, the text in comments is reformatted to standardise and
181 indent it nicely ... the reformatting is not performed on any text
182 inside an <example> element. When the text is reformatted, it is bro‐
183 ken into whitespace separated “words” which are then subjected to some
184 extra processing ...
185 Certain well known constants such as YES, NO, and nil are enclosed
187 in <code> ... </code> markup.
188 The names of method arguments within method descriptions are
190 enclosed in <var> ... </var> markup.
191 Method names (beginning with a plus or minus) are enclosed in
193 <ref...> ... </ref> markup. E.g. "-init" (without the quotes)
194 would be wrapped in a GSDoc reference element to point to the init
195 method of the current class or, if only one known class had an init
196 method, it would refer to the method of that class. Note the fact
197 that the method name must be surrounded by whitespace to be recog‐
198 nized (though a comma, fullstop, or semicolon at the end of the
199 specifier will act like whitespace).
200 Method specifiers including class names (beginning and ending with
202 square brackets) are enclosed in <ref...> ... </ref> markup. e.g.
203 '[NSObject-init]', will create a reference to the init method of
204 NSObject (either the class proper, or any of its categories), while
205 '[(NSCopying)-copyWithZone:]', creates a reference to a method in
206 the NSCopying protocol. Note that no spaces must appear between
207 the square brackets in these specifiers. Protocol names are
208 enclosed in round brackets rather than the customary angle brack‐
209 ets, because GSDoc is an XML language, and XML treats angle brack‐
210 ets specially.
211 Function names (ending with '()') other than 'main()' are enclosed
213 in <ref...> ... </ref> markup. E.g. "NSLogv()" (without the
214 quotes) would be wrapped in a GSDoc reference element to point to
215 the documentation of the NSLog function. Note the fact that the
216 function name must be surrounded by whitespace (though a comma,
217 fullstop, or semicolon at the end of the specifier will also act as
218 a whitespace terminator).
219
222 The tool accepts certain user defaults (which can of course be supplied
223 as command-line arguments by prepending '-' before the default name and
224 giving the value afterwards, as in -Clean YES):
225 Clean
227 If this boolean value is set to YES, then rather than generating
228 documentation, the tool removes all GSDoc files generated in the
229 project, and all html files generated from them (as well as any
230 which would be generated from GSDoc files listed explicitly), and
231 finally removes the project index file. The only exception to this
232 is that template GSDoc files (i.e. those specified using "-Con‐
233 stantsTemplate ...", "-FunctionsTemplate ..." arguments etc) are
234 not deleted unless the CleanTemplates flag is set.
235 CleanTemplates
237 This flag specifies whether template GSDoc files are to be removed
238 along with other files when the Clean option is specified. The
239 default is for them not to be removed ... since these templates may
240 have been produced manually and just had data inserted into them.
241 ConstantsTemplate
243 Specify the name of a template document into which documentation
244 about constants should be inserted from all files in the project.
245 This is useful if constants in the source code are scattered around
246 many files, and you need to group them into one place. You are
247 responsible for ensuring that the basic template document (into
248 which individual constant documentation is inserted) contains all
249 the other information you want, but as a convenience autogsdoc will
250 generate a simple template (which you may then edit) for you if the
251 file does not exist. Insertion takes place immediately before the
252 back element (or if that does not exist, immediately before the end
253 of the body element) in the template.
254 Declared
256 Specify where headers are to be documented as being found. The
257 actual name produced in the documentation is formed by appending
258 the last component of the header file name to the value of this
259 default. If this default is not specified, the full name of the
260 header file (as supplied on the command line), with the HeaderDi‐
261 rectory default prepended, is used. A typical usage of this might
262 be '"-Declared Foundation"' when generating documentation for the
263 GNUstep base library. This would result in the documentation say‐
264 ing that NSString is declared in 'Foundation/NSString.h'
265 DocumentAllInstanceVariables
267 This flag permits you to generate documentation for all instance
268 variables. Normally, only those explicitly declared 'public' or
269 'protected' will be documented.
270 DocumentInstanceVariables
272 This flag permits you to turn off documentation for instance vari‐
273 ables completely. Normally, explicitly declared 'public' or 'pro‐
274 tected' instance variables will be documented.
275 InstanceVariablesAtEnd
277 This flag, if set, directs the HTML generator to place instance
278 variable documentation at the end of the class, instead of the
279 beginning. This is useful if you use a lot of protected instance
280 variables which are only going to be of secondary interest to gen‐
281 eral users of the class.
282 DocumentationDirectory
284 May be used to specify the directory in which generated documenta‐
285 tion is to be placed. If this is not set, output is placed in the
286 current directory. This directory is also used as a last resort to
287 locate source files (not headers), and more importantly, it is used
288 as the first and only resort to locate any .gsdoc files that are
289 passed in on the command line. Any path information given for
290 these files is removed and they are searched for in 'Documenta‐
291 tionDirectory' (even though they may not have been autogenerated).
292 Files
294 Specifies the name of a file containing a list of file names as a
295 property list array (name1,name2,...) format. If this is present,
296 filenames in the program argument list are ignored and the names in
297 this file are used as the list of names to process.
298 FunctionsTemplate
300 Specify the name of a template document into which documentation
301 about functions should be inserted from all files in the project.
302 This is useful if function source code is scattered around many
303 files, and you need to group it into one place. You are responsi‐
304 ble for ensuring that the basic template document (into which indi‐
305 vidual function documentation is inserted) contains all the other
306 information you want, but as a convenience autogsdoc will generate
307 a simple template (which you may then edit) for you if the file
308 does not exist. Insertion takes place immediately before the back
309 element (or if that does not exist, immediately before the end of
310 the body element) in the template.
311 GenerateHtml
313 May be used to specify if HTML output is to be generated. Defaults
314 to YES.
315 HeaderDirectory
317 May be used to specify the directory to be searched for header
318 files. When supplied, this value is prepended to relative header
319 names, otherwise the relative header names are interpreted relative
320 to the current directory. Header files specified as absolute paths
321 are not influenced by this default.
322 IgnoreDependencies
324 A boolean value which may be used to specify that the program
325 should ignore file modification times and regenerate files anyway.
326 Provided for use in conjunction with the 'make' system, which is
327 expected to manage dependency checking itsself.
328 LocalProjects
330 This value is used to control the automatic inclusion of local
331 external projects into the indexing system for generation of cross-
332 references in final document output. If set to 'None', then no
333 local project references are done, otherwise, the 'Local' GNUstep
334 documentation directory is recursively searched for files with a
335 '.igsdoc' extension, and the indexing information from those files
336 is used. The value of this string is also used to generate the
337 filenames in the cross reference ... if it is an empty string, the
338 path to use is assumed to be a file in the same directory where the
339 igsdoc file was found, otherwise it is used as a prefix to the name
340 in the index. NB. Local projects with the same name as the project
341 currently being documented will not be included by this mechanism.
342 If you wish to include such projects, you must do so explicitly
343 using -Projects ...
344 MacrosTemplate
346 Specify the name of a template document into which documentation
347 about macros should be inserted from all files in the project.
348 This is useful if macro code is scattered around many files, and
349 you need to group it into one place. You are responsible for
350 ensuring that the basic template document (into which individual
351 macro documentation is inserted) contains all the other information
352 you want, but as a convenience autogsdoc will generate a simple
353 template (which you may then edit) for you if the file does not
354 exist. Insertion takes place immediately before the back element
355 (or if that does not exist, immediately before the end of the body
356 element) in the template.
357 MakeDependencies
359 A filename to be used to output dependency information for make.
360 This will take the form of listing all header and source files
361 known for the project as dependencies of the project name (see
362 'Project').
363 Project
365 May be used to specify the name of this project ... determines the
366 name of the index reference file produced as part of the documenta‐
367 tion to provide information enabling other projects to cross-refer‐
368 ence to items in this project.
369 Projects
371 This value may be supplied as a dictionary containing the paths to
372 the igsdoc index/reference files used by external projects, along
373 with values to be used to map the filenames found in the indexes.
374 For example, if a project index (igsdoc) file says that the class
375 'Foo' is found in the file 'Foo', and the path associated with that
376 project index is '/usr/doc/proj', Then generated html output may
377 reference the class as being in '/usr/doc/prj/Foo.html' . Note
378 that a dictionary may be given on the command line by using the
379 standard PropertyList format (not the XML format of OS X), using
380 semicolons as line-separators, and enclosing it in single quotes.
381 ShowDependencies
383 A boolean value which may be used to specify that the program
384 should log which files are being regenerated because of their
385 dependencies on other files.
386 Standards
388 A boolean value used to specify whether the program should insert
389 information about standards complience into the documentation.
390 This should only be used when documenting the GNUstep libraries and
391 tools themselves as it assumes that the code being documented is
392 part of GNUstep and possibly complies with the OpenStep standard or
393 implements MacOS-X compatible methods.
394 SystemProjects
396 This value is used to control the automatic inclusion of system
397 external projects into the indexing system for generation of cross-
398 references in final document output. If set to 'None', then no
399 system project references are done, otherwise, the 'System' GNUstep
400 documentation directory is recursively searched for files with a
401 '.igsdoc' extension, and the indexing information from those files
402 is used. The value of this string is also used to generate the
403 filenames in the cross reference ... if it is an empty string, the
404 path to use is assumed to be a file in the same directory where the
405 igsdoc file was found, otherwise it is used as a prefix to the name
406 in the index. NB. System projects with the same name as the
407 project currently being documented will not be included by this
408 mechanism. If you wish to include such projects, you must do so
409 explicitly using -Projects ...
410 TypedefsTemplate
412 Specify the name of a template document into which documentation
413 about typedefs should be inserted from all files in the project.
414 This is useful if typedef source code is scattered around many
415 files, and you need to group it into one place. You are responsi‐
416 ble for ensuring that the basic template document (into which indi‐
417 vidual typedef documentation is inserted) contains all the other
418 information you want, but as a convenience autogsdoc will generate
419 a simple template (which you may then edit) for you if the file
420 does not exist. Insertion takes place immediately before the back
421 element (or if that does not exist, immediately before the end of
422 the body element) in the template.
423 Up A string used to supply the name to be used in the 'up' link from
425 generated GSDoc documents. This should normally be the name of a
426 file which contains an index of the contents of a project. If this
427 is missing or set to an empty string, then no 'up' link will be
428 provided in the documents.
429 VariablesTemplate
431 Specify the name of a template document into which documentation
432 about variables should be inserted from all files in the project.
433 This is useful if variable source code is scattered around many
434 files, and you need to group it into one place. You are responsi‐
435 ble for ensuring that the basic template document (into which indi‐
436 vidual variable documentation is inserted) contains all the other
437 information you want, but as a convenience autogsdoc will generate
438 a simple template (which you may then edit) for you if the file
439 does not exist. Insertion takes place immediately before the back
440 element (or if that does not exist, immediately before the end of
441 the body element) in the template.
442 Verbose
444 A boolean used to specify whether you want verbose debug/warning
445 output to be produced.
446 Warn
448 A boolean used to specify whether you want standard warning output
449 (e.g. report of undocumented methods) produced.
450 WordMap
452 This value is a dictionary used to map identifiers/keywords found
453 in the source files to other words. Generally you will not have
454 to use this, but it is sometimes helpful to avoid the parser being
455 confused by the use of C preprocessor macros. You can effectively
456 redefine the macro to something less confusing. The value you map
457 the identifier to must be one of - Another identifier, An empty
458 string - the value is ignored, Two slashes ('//') - the rest of the
459 line is ignored. Note that a dictionary may be given on the com‐
460 mand line by using the standard PropertyList format (not the XML
461 format of OS X), using semicolons as line-separators, and enclosing
462 it in single quotes.
463
466 The 'Up' default is used to specify the name of a document which should
467 be used as the 'up' link for any other documents used. This name must
468 not include a path or extension. Generally, the document referred to by
469 this default should be a hand-edited GSDoc document which should have a
470 <em>back</em> section containing a project index. e.g.
471 <?xml version="1.0"?>
473 <!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
474 "http://www.gnustep.org/gsdoc-1_0_3.xml">
475 <gsdoc base="index">
476 <head>
477 <title>My project reference</title>
478 <author name="my name"></author>
479 </head>
480 <body>
481 <chapter>
482 <heading>My project reference</heading>
483 </chapter>
484 <back>
485 <index scope="project" type="title" />
486 </back>
487 </body>
488 </gsdoc>
489
492 Source: .h, .m, .c
493 GSDoc: .gsdoc
494 Index: .igsdoc
495 HTML: .html
496
499 Several GSDoc elements are not rendered properly into HTML yet. These
500 are: <prjref>, <EOEntity>, <EOModel>.
501
504 Error messages and warnings can come from each of the stages of the
505 pipeline: top-level control, source parsing, GSDoc parsing, and index‐
506 ing.
507
510 gsdoc(7), GNUstep(7)
511
513 Autogsdoc combined the capabilities of two earlier tools, 'autodoc' and
514 'gsdoc', which performed the source->GSDoc and GSDoc->HTML translations
515 respectively. These earlier tools and the GSDoc format were developed
516 for GNUstep based on the earlier GDML SGML language.
517 This manual page first appeared in gnustep-base 1.9.2 (March 2004).
519
521 autogsdoc was written by Richard Frith-Macdonald <rfm@gnu.org>
522 This manual page added by Adrian Robert <arobert@cogsci.ucsd.edu>.
524GNUstep March 2004 AUTOGSDOC(1)