SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from OpenSuSE gnustep-base-1.26.0-35.1.x86_64.rpm

AUTOGSDOC

Section: GNUstep System Manual (1)
Updated: March 2004
Index 

NAME

autogsdoc - GNUstep API documentation generator and XML->HTML converter

 

SYNOPSIS

autogsdoc[-Filesfilename][-GenerateHtmlYES|no][-Cleanyes|NO][-CleanTemplatesyes|NO][-IgnoreDependenciesyes|NO][-MakeDependenciesyes|NO][-ShowDependenciesyes|NO][-HeaderDirectorypath][-DocumentationDirectorypath][-Declaredlocation][-Projecttitle][-Standardsyes|NO][-DocumentAllInstanceVariablesyes|NO][-DocumentInstanceVariablesYES|no][-InstanceVariablesAtEndyes|NO][-ConstantsTemplatefilename][-FunctionsTemplatefilename][-MacrosTemplatefilename][-TypedefsTemplatefilename][-VariablesTemplatefilename][-SystemProjectsstring][-LocalProjectsstring][-ProjectsdictString][-Verboseyes|NO][-Warnyes|NO][-WordMapdictString][files]

 

DESCRIPTION

The autogsdoc tool is a command-line utility that helps developers producereference documentation for GNUstep APIs. It also enables developers to writeand maintain other documentation in XML and have it converted to HTML. Indetail, autogsdoc will:
-
Extract special comments describing the public interfaces of classes,categories, protocols, functions, and macros from Objective C sourcecode (header files and optionally source files) into GSDoc XML files.
-
Convert GSDoc XML files, whether generated from source code orwritten manually by developers, into HTML.
-
Construct indices based on GSDoc XML file sets, and convert thoseto HTML as well.

The most common usage this is to run the command with one or more header filenames as arguments ... the tool will automatically parse corresponding sourcefiles in the same directory as the headers (or the current directory, or thedirectory specified using the DocumentationDirectory default), and produceGSDoc and HTML files as output. For best results this mode should be run fromthe directory containing the source files. (Note that since C is a subset ofObjective C, this tool can operate to document functions and other Cstructures in plain C source.)GSDoc files may also be given directly in addition or by themselves, and willbe converted to HTML. See the GSDoc HTML documentation or the gsdoc(7) manpage for information on the GSDoc format.Finally, HTML files may be given on the command line. Cross-referencesto other parts of code documentation found within them will be rewrittenbased on what is found in the project currently.

 

SOURCE CODE MARKUP

The source code parser will automatically produce GSDoc documentslisting the methods in the classes found in the source files, and itwill include text from specially formatted comments from the sourcefiles.Any comment beginning with slash andtwoasterisks rather than the common slash and single asterisk, is taken to beGSDoc markup, to be use as the description of the class or method followingit. This comment text is reformatted and then inserted into the output.
Where multiple comments are associated with the same item, they are joinedtogether with a line break (<br/>) between each if necessary.The tool can easily be used to document programs as well as libraries,simply by giving it the name of the source file containing the main()function of the program - it takes the special comments from thatfunction and handles them specially, inserting them as a section atthe end of the first chapter of the document (it creates the firstchapter if necessary).Optionsare described in the sectionArguments and Defaultsbelow.

 

EXTRA MARKUP

There are some cases where special extra processing is performed,predominantly in the first comment found in the source file, from whichvarious chunks of GSDoc markup may be extracted and placed into appropriatelocations in the output document -
AutogsdocSource:
In any line whereAutogsdocSource:is found, the remainder of the line is taken as a source file name to be usedinstead of making the assumption that each .h file processed uses a .m file ofthe same name. You may supply multipleAutogsdocSource:lines where a header file declares items which are defined in multiple sourcefiles. If a file name is absolute, it is used just as supplied. If on theother hand, it is a relative path, the software looks for the source filefirst relative to the location of the header file, and if not found there,relative to the current directory in which autogsdoc is running, and finallyrelative to the directory specified by theDocumentationDirectorydefault.
<abstract>
An abstract of the content of the document ... placed in the head of the GSDocoutput.
<author>
A description of the author of the code - may be repeated to handlethe case where a document has multiple authors. Placed in thehead of the GSDoc output.As an aid to readability of the source, some special additionalprocessing is performed related to the document author -Any line of the form'Author:name <email-address>', or'By:name <email-address>', or'Author:name' or'By:name' will be recognised and converted to anauthorelement, possibly containing anemailelement.
<back>
Placed in the GSDoc output just before the end of the body of the document -intended to be used for appendices, index etc..
<chapter>
Placed immediately before any generated class documentation ...intended to be used to provide overall description of how thecode being documented works. Any documentation for the main()function of a program is inserted as a section at the end of thischapter.
<copy>
Copyright of the content of the document ... placed in the head of the GSDocoutput. As an aid to readability of the source, some special additionalprocessing is performed - Any line of the form 'Copyright (C) text' will berecognised and converted to acopyelement.
<date>
Date of the revision of the document ... placed in the headof the GSDoc output. If this is omitted the tool will try toconstruct a value from the RCS Date tag (if available).
<front>
Inserted into the document at the start of the body ... intendedto provide for introduction or contents pages etc.
<title>
Title of the document ... placed in the head of the GSDoc output.If this is omitted the tool will generate a (probably poor)title of its own - so you should include this markup manually.
<version>
Version identifier of the document ... placed in the headof the GSDoc output. If this is omitted the tool will try toconstruct a value from the RCS Revision tag (if available).NBThe markup just described may be used within class, category, or protocoldocumentation ... if so, it is extracted and wrapped round the rest of thedocumentation for the class as the class's chapter. The rest of the classdocumentation is normally inserted at the end of the chapter, but may insteadbe substituted in in place of the <unit> pseudo-element within the <chapter>element.

 

METHOD MARKUP

In comments being used to provide text for a method description, thefollowing markup is removed from the text and handled specially -
<init>
The method is marked as being the designated initialiser for the class.
<override-subclass>
The method is marked as being one which subclasses must override(e.g. an abstract method).
<override-never>
The method is marked as being one which subclasses shouldNOToverride.
<standards>
The markup is removed from the description and placedafterit in the GSDoc output - so that the method is described asconforming (or not conforming) to the specified standards.

 

AUTOMATED MARKUP

Generally, the text in comments is reformatted to standardise andindent it nicely ... the reformatting isnotperformed on any text inside an <example> element. When the text isreformatted, it is broken into whitespace separated ``words''which are then subjected to some extra processing ...
Certain well known constants such as YES, NO, and nil are enclosed in <code>... </code> markup.
The names of method arguments within method descriptions are enclosed in<var> ... </var> markup.
Method names (beginning with a plus or minus) are enclosed in <ref...>... </ref> markup. E.g. "-init" (without the quotes) would bewrapped in a GSDoc reference element to point to the init method of thecurrent class or, if only one known class had an init method, it would referto the method of that class. Note the fact that the method name must besurrounded by whitespace to be recognized (though a comma, fullstop, orsemicolon at the end of the specifier will act like whitespace).
Method specifiers including class names (beginning and ending with squarebrackets) are enclosed in <ref...> ... </ref> markup.e.g. '[NSObject-init]', will create a reference to the init method of NSObject(either the class proper, or any of its categories), while'[(NSCopying)-copyWithZone:]', creates a reference to a method in theNSCopying protocol. Note that no spaces must appear between the squarebrackets in these specifiers. Protocol names are enclosed in roundbrackets rather than the customary angle brackets, because GSDoc is an XMLlanguage, and XML treats angle brackets specially.
Function names (ending with '()') other than 'main()' are enclosed in<ref...> ... </ref> markup. E.g. "NSLogv()" (without thequotes) would be wrapped in a GSDoc reference element to point to thedocumentation of the NSLog function. Note the fact that the functionname must be surrounded by whitespace (though a comma, fullstop, or semicolonat the end of the specifier will also act as a whitespace terminator).

 

ARGUMENTS AND DEFAULTS

The tool accepts certain user defaults (which can of course besupplied as command-line arguments by prepending '-' before thedefault name and giving the value afterwards, as in -Clean YES):
Clean
If this boolean value is set to YES, then rather than generatingdocumentation, the tool removes all GSDoc files generated in theproject, and all html files generated from them (as well as any whichwould be generated from GSDoc files listed explicitly), and finallyremoves the project index file. The only exception to this is thattemplate GSDoc files (i.e. those specified using"-ConstantsTemplate ...", "-FunctionsTemplate ..." arguments etc)are not deleted unless the CleanTemplates flag is set.
CleanTemplates
This flag specifies whether template GSDoc files are to be removedalong with other files when the Clean option is specified.The default is for them not to be removed ... since these templatesmay have been produced manually and just had data inserted into them.
ConstantsTemplate
Specify the name of a template document into which documentationabout constants should be inserted from all files in the project.This is useful if constants in the source code are scattered around manyfiles, and you need to group them into one place.You are responsible for ensuring that the basic template document(into which individual constant documentation is inserted) containsall the other information you want, but as a convenience autogsdocwill generate a simple template (which you may then edit) for youif the file does not exist.Insertion takes place immediately before thebackelement (or if that does not exist, immediately before the endof thebodyelement) in the template.
Declared
Specify where headers are to be documented as being found. The actualname produced in the documentation is formed by appending the lastcomponent of the header file name to the value of this default. Ifthis default is not specified, the full name of the header file (assupplied on the command line), with the HeaderDirectory defaultprepended, is used. A typical usage of this might be '"-DeclaredFoundation"' when generating documentation for the GNUstep baselibrary. This would result in the documentation saying that NSStringis declared in 'Foundation/NSString.h'
DocumentAllInstanceVariables
This flag permits you to generate documentation for all instancevariables. Normally, only those explicitly declared 'public' or'protected' will be documented.
DocumentInstanceVariables
This flag permits you to turn off documentation for instance variablescompletely. Normally, explicitly declared 'public' or 'protected' instancevariables will be documented.
InstanceVariablesAtEnd
This flag, if set, directs the HTML generator to place instance variabledocumentation at the end of the class, instead of the beginning. This isuseful if you use a lot of protected instance variables which are only goingto be of secondary interest to general users of the class.
DocumentationDirectory
May be used to specify the directory in which generated documentationis to be placed. If this is not set, output is placed in the currentdirectory. This directory is also used as a last resort to locatesource files (not headers), and more importantly, it is used as thefirst and onlyresort to locate any .gsdoc filesthat are passed in on the command line. Any path information givenfor these files isremovedand they are searched for in 'DocumentationDirectory' (even though theymay not have been autogenerated).
Files
Specifies the name of a file containing a list of file names asa property list array(name1,name2,...)format. If this is present, filenames in the program argument list areignored and the names in this file are used as the list of names to process.
FunctionsTemplate
Specify the name of a template document into which documentationabout functions should be inserted from all files in the project.This is useful if function source code is scattered around manyfiles, and you need to group it into one place.You are responsible for ensuring that the basic template document(into which individual function documentation is inserted) containsall the other information you want, but as a convenience autogsdocwill generate a simple template (which you may then edit) for youif the file does not exist.Insertion takes place immediately before thebackelement (or if that does not exist, immediately before the endof thebodyelement) in the template.
GenerateHtml
May be used to specify if HTML output is to be generated.Defaults to YES.
HeaderDirectory
May be used to specify the directory to be searched for header files.When supplied, this value is prepended to relative header names,otherwise the relative header names are interpreted relative tothe current directory.Header files specified as absolute paths are not influenced by thisdefault.
IgnoreDependencies
A boolean value which may be used to specify that the program shouldignore file modification times and regenerate files anyway. Providedfor use in conjunction with the 'make' system, which isexpected to manage dependency checking itsself.
LocalProjects
This value is used to control the automatic inclusion of localexternal projects into the indexing system for generation ofcross-references in final document output.If set to 'None', then no local project references are done,otherwise, the 'Local' GNUstep documentation directory is recursivelysearched for files with a '.igsdoc' extension, and theindexing information from those files is used.The value of this string is also used to generate the filenames inthe cross reference ... if it is an empty string, the path to useis assumed to be a file in the same directory where the igsdocfile was found, otherwise it is used as a prefix to the name inthe index.NB. Local projects with the same name as the project currentlybeing documented willnotbe included by this mechanism.If you wish to include such projects, you must do so explicitlyusing -Projects ...
MacrosTemplate
Specify the name of a template document into which documentationabout macros should be inserted from all files in the project.This is useful if macro code is scattered around manyfiles, and you need to group it into one place.You are responsible for ensuring that the basic template document(into which individual macro documentation is inserted) containsall the other information you want, but as a convenience autogsdocwill generate a simple template (which you may then edit) for youif the file does not exist.Insertion takes place immediately before the backelement (or if that does not exist, immediately before the endof the body
 element) in the template.
MakeDependencies
A filename to be used to output dependency information for make. Thiswill take the form of listing all header and source files known forthe project as dependencies of the project name (see'Project').
Project
May be used to specify the name of this project ... determines thename of the index reference file produced as part of the documentationto provide information enabling other projects to cross-reference toitems in this project.
Projects
This value may be supplied as a dictionary containing the paths tothe igsdoc index/reference files used by external projects, alongwith values to be used to map the filenames found in the indexes.For example, if a project index (igsdoc) file says that the class'Foo' is found in the file 'Foo', and thepath associated with that project index is '/usr/doc/proj',Then generated html output may reference the class as being in'/usr/doc/prj/Foo.html' . Note that a dictionary may begiven on the command line by using the standard PropertyList format(not the XML format of OS X), using semicolons as line-separators, andenclosing it in single quotes.
ShowDependencies
A boolean value which may be used to specify that the program shouldlog which files are being regenerated because of their dependencieson other files.
Standards
A boolean value used to specify whether the program should insertinformation about standards complience into the documentation.This should only be used when documenting the GNUstep librariesand tools themselves as it assumes that the code being documentedis part of GNUstep and possibly complies with the OpenStep standardor implements MacOS-X compatible methods.
SystemProjects
This value is used to control the automatic inclusion of systemexternal projects into the indexing system for generation ofcross-references in final document output.If set to 'None', then no system project references are done,otherwise, the 'System' GNUstep documentation directory is recursivelysearched for files with a '.igsdoc' extension, and theindexing information from those files is used.The value of this string is also used to generate the filenames inthe cross reference ... if it is an empty string, the path to useis assumed to be a file in the same directory where the igsdocfile was found, otherwise it is used as a prefix to the name inthe index.NB. System projects with the same name as the project currentlybeing documented will notbe included by this mechanism.If you wish to include such projects, you must do so explicitlyusing -Projects ...
TypedefsTemplate
Specify the name of a template document into which documentationabout typedefs should be inserted from all files in the project.This is useful if typedef source code is scattered around manyfiles, and you need to group it into one place.You are responsible for ensuring that the basic template document(into which individual typedef documentation is inserted) containsall the other information you want, but as a convenience autogsdocwill generate a simple template (which you may then edit) for youif the file does not exist.Insertion takes place immediately before the backelement (or if that does not exist, immediately before the endof the bodyelement) in the template.
Up
A string used to supply the name to be used in the 'up' link fromgenerated GSDoc documents. This should normally be the name of afile which contains an index of the contents of a project.If this is missing or set to an empty string, then no 'up' linkwill be provided in the documents.
VariablesTemplate
Specify the name of a template document into which documentationabout variables should be inserted from all files in the project.This is useful if variable source code is scattered around manyfiles, and you need to group it into one place.You are responsible for ensuring that the basic template document(into which individual variable documentation is inserted) containsall the other information you want, but as a convenience autogsdocwill generate a simple template (which you may then edit) for youif the file does not exist.Insertion takes place immediately before the backelement (or if that does not exist, immediately before the endof the bodyelement) in the template.
Verbose
A boolean used to specify whether you want verbose debug/warningoutput to be produced.
Warn
A boolean used to specify whether you want standard warningoutput (e.g. report of undocumented methods) produced.
WordMap
This value is a dictionary used to map identifiers/keywords foundin the source files to other words. Generally you will not haveto use this, but it is sometimes helpful to avoid the parser beingconfused by the use of C preprocessor macros. You can effectivelyredefine the macro to something less confusing.The value you map the identifier to must be one of -Another identifier,An empty string - the value is ignored,Two slashes ('//') - the rest of the line is ignored.Note that a dictionary may be given on the command line by using thestandard PropertyList format (not the XML format of OS X), usingsemicolons as line-separators, and enclosing it in single quotes.

 

INTER-DOCUMENT LINKAGE

The 'Up' default is used to specify the name of a document which should beused as the 'up' link for any other documents used. This name must notinclude a path or extension. Generally, the document referred to by thisdefault should be a hand-edited GSDoc document which should have a<em>back</em> section containing a project index. e.g.<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"

                        "http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">

  <head>

    <title>My project reference</title>

    <author name="my name"></author>

  </head>

  <body>

    <chapter>

      <heading>My project reference</heading>

    </chapter>

    <back>

      <index scope="project" type="title" />

    </back>

  </body>
</gsdoc>

 

FILES

Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .html

 

BUGS

Several GSDoc elements are not rendered properly into HTML yet. Theseare: <prjref>, <EOEntity>, <EOModel>.

 

DIAGNOSTICS

Error messages and warnings can come from each of the stages of the pipeline:top-level control, source parsing, GSDoc parsing, and indexing.

 

SEE ALSO

gsdoc(7), GNUstep(7) 

HISTORY

Autogsdoc combined the capabilities of two earliertools, 'autodoc' and 'gsdoc', which performed the source->GSDoc andGSDoc->HTML translations respectively. These earlier tools and the GSDocformat were developed for GNUstep based on the earlier GDML SGML language.This manual page first appeared in gnustep-base 1.9.2 (March 2004). 

AUTHORS

autogsdocwas written by Richard Frith-Macdonald <rfmAATTgnu.org>This manual page added by Adrian Robert <arobertAATTcogsci.ucsd.edu>.


 

Index

NAME
SYNOPSIS
DESCRIPTION
SOURCE CODE MARKUP
EXTRA MARKUP
METHOD MARKUP
AUTOMATED MARKUP
ARGUMENTS AND DEFAULTS
INTER-DOCUMENT LINKAGE
FILES
BUGS
DIAGNOSTICS
SEE ALSO
HISTORY
AUTHORS

This document was created byman2html,using the manual pages.