gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-05-30 16:30:41 +00:00
Code Issues Projects Releases Packages Wiki Activity

Fix various minor documentation bugs.

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@14777 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
CaS 2002-10-14 11:05:49 +00:00
parent 7e200afc11
commit e7abf9d81c
6 changed files with 516 additions and 433 deletions
Download patch file Download diff file Expand all files Collapse all files

5
Headers/gnustep/base/NSObject.h
View file

@ -189,7 +189,7 @@
* class of the object to be aClass etc. The allocated memory will * class of the object to be aClass etc. The allocated memory will
* be extraBytes larger than the space actually needed to hold the * be extraBytes larger than the space actually needed to hold the
* instance variables of the object.<br /> * instance variables of the object.<br />
* This function is used by the [NSObject-allocWithZone:] mnethod. * This function is used by the [NSObject+allocWithZone:] mnethod.
*/ */
GS_EXPORT NSObject * GS_EXPORT NSObject *
NSAllocateObject(Class aClass, unsigned extraBytes, NSZone *zone); NSAllocateObject(Class aClass, unsigned extraBytes, NSZone *zone);
@ -206,7 +206,8 @@ NSDeallocateObject(NSObject *anObject);
* memory allocated from zone. The allocated memory will be extraBytes * memory allocated from zone. The allocated memory will be extraBytes
* longer than that necessary to actually store the instance variables * longer than that necessary to actually store the instance variables
* of the copied object.<br /> * of the copied object.<br />
* This is used by the [NSObject-copyWithZone:] method. * This is used by the NSObject implementation of the
* [(NSCopying)-copyWithZone:] method.
*/ */
GS_EXPORT NSObject * GS_EXPORT NSObject *
NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone); NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone);

2
Source/NSObjCRuntime.m
View file

@ -510,7 +510,7 @@ GSGetValue(NSObject *self, NSString *key, SEL sel,
* supplied).<br /> * supplied).<br />
* Automatic conversion between NSNumber and C scalar types is performed.<br /> * Automatic conversion between NSNumber and C scalar types is performed.<br />
* If type is null and can't be determined from the selector, the * If type is null and can't be determined from the selector, the
* [NSObject-handleTakevalue:forUnboundKey:] method is called to try * [NSObject-handleTakeValue:forUnboundKey:] method is called to try
* to set a value. * to set a value.
*/ */
void void

19
Tools/AGSHtml.m
View file

@ -188,8 +188,8 @@ static NSMutableSet *textNodes = nil;
if (u == nil) if (u == nil)
{ {
u = unit; u = unit;
s = base;
} }
s = base;
} }
else if (u == nil) else if (u == nil)
{ {
@ -215,7 +215,7 @@ static NSMutableSet *textNodes = nil;
s = [globalRefs unitRef: r type: t unit: &u]; s = [globalRefs unitRef: r type: t unit: &u];
} }
} }
else if (s == nil)
{ {
NSString *tmp = u; NSString *tmp = u;
@ -1448,12 +1448,12 @@ static NSMutableSet *textNodes = nil;
NSString *type = [prop objectForKey: @"type"]; NSString *type = [prop objectForKey: @"type"];
NSString *r = [prop objectForKey: @"id"]; NSString *r = [prop objectForKey: @"id"];
GSXMLNode *tmp = [node firstChild]; GSXMLNode *tmp = [node firstChild];
NSString *c = [prop objectForKey: @"class"];
NSString *s; NSString *s;
if ([type isEqual: @"method"] || [type isEqual: @"ivariable"]) if ([type isEqual: @"method"] || [type isEqual: @"ivariable"])
{ {
s = [prop objectForKey: @"class"]; s = [self makeLink: r ofType: type inUnit: c isRef: YES];
s = [self makeLink: r ofType: type inUnit: s isRef: YES];
} }
else else
{ {
@ -1470,7 +1470,16 @@ static NSMutableSet *textNodes = nil;
} }
if (s == nil) if (s == nil)
{ {
NSLog(@"ref '%@' not found for %@", r, type); if (c == nil)
{
NSLog(@"No unique ref to %@ '%@' not found in %@",
type, r, base);
}
else
{
NSLog(@"ref to the %@ version of %@ '%@' not found in %@",
c, type, r, base);
}
if (tmp == nil) if (tmp == nil)
{ {
[buf appendString: r]; [buf appendString: r];

56
Tools/AGSOutput.m
View file

@ -69,6 +69,11 @@ static BOOL snuggleStart(NSString *t)
* far too special purpose.</p> * far too special purpose.</p>
* <unit /> * <unit />
* <p>Here is the afterword for the class.</p> * <p>Here is the afterword for the class.</p>
* <p> Ad here is some automated cross referencing ...
* A method in a protocol: [(NSCopying)-copyWithZone:], a class:
* [NSString], a protocol: [(NSCopying)], and a
* category: [NSRunLoop(GNUstepExtensions)].
* </p>
* </unit> * </unit>
* And finally, here is the actual class description ... outside the chapter. * And finally, here is the actual class description ... outside the chapter.
* With a reference to foo() in it. * With a reference to foo() in it.
@ -1809,6 +1814,7 @@ static BOOL snuggleStart(NSString *t)
/* /*
* Ensure that methods are rendered as references. * Ensure that methods are rendered as references.
* First look for format with class name in square brackets. * First look for format with class name in square brackets.
* If that's all there is, we make a class reference.
*/ */
r = [tmp rangeOfString: @"["]; r = [tmp rangeOfString: @"["];
if (r.length > 0) if (r.length > 0)
@ -1824,6 +1830,7 @@ static BOOL snuggleStart(NSString *t)
NSString *cName = nil; NSString *cName = nil;
NSString *mName = nil; NSString *mName = nil;
unichar c; unichar c;
BOOL isProtocol = NO;
if (pos < ePos if (pos < ePos
&& [identStart characterIsMember: && [identStart characterIsMember:
@ -1880,8 +1887,7 @@ static BOOL snuggleStart(NSString *t)
cName = [tmp substringWithRange: r]; cName = [tmp substringWithRange: r];
} }
} }
else if (pos < ePos else if (pos < ePos && (c = [tmp characterAtIndex: pos]) == '(')
&& (c = [tmp characterAtIndex: pos]) == '(')
{ {
/* /*
* Look for protocol name. * Look for protocol name.
@ -1903,6 +1909,7 @@ static BOOL snuggleStart(NSString *t)
} }
pos++; pos++;
} }
isProtocol = YES;
} }
if (pos < ePos && (c == '+' || c == '-')) if (pos < ePos && (c == '+' || c == '-'))
@ -1986,6 +1993,23 @@ static BOOL snuggleStart(NSString *t)
ref = [NSString stringWithFormat: ref = [NSString stringWithFormat:
@"<ref type=\"method\" id=\"%@\">", mName]; @"<ref type=\"method\" id=\"%@\">", mName];
} }
else if (isProtocol == YES)
{
ref = [NSString stringWithFormat:
@"<ref type=\"method\" id=\"%@\" class=\"%@\">",
mName, cName];
if (isProtocol == YES)
{
if (sub == nil)
{
sub = tmp;
}
sub = [sub stringByReplacingString: @"("
withString: @"&lt;"];
sub = [sub stringByReplacingString: @")"
withString: @"&gt;"];
}
}
else else
{ {
ref = [NSString stringWithFormat: ref = [NSString stringWithFormat:
@ -2005,6 +2029,34 @@ static BOOL snuggleStart(NSString *t)
[a insertObject: end atIndex: ++l]; [a insertObject: end atIndex: ++l];
} }
} }
else if (pos == ePos && cName != nil)
{
NSString *ref;
if (isProtocol == YES)
{
NSRange r;
r = NSMakeRange(1, [cName length] - 2);
cName = [cName substringWithRange: r];
ref = [NSString stringWithFormat:
@"<ref type=\"protocol\" id=\"(%@)\">&lt;%@&gt;</ref>",
cName, cName];
}
else if ([cName hasSuffix: @")"] == YES)
{
ref = [NSString stringWithFormat:
@"<ref type=\"category\" id=\"%@\">%@</ref>",
cName, cName];
}
else
{
ref = [NSString stringWithFormat:
@"<ref type=\"class\" id=\"%@\">%@</ref>",
cName, cName];
}
[a replaceObjectAtIndex: l withObject: ref];
}
} }
continue; continue;
} }

865
Tools/autogsdoc.m
View file

@ -20,428 +20,449 @@
<chapter> <chapter>
<heading>The autogsdoc tool</heading> <heading>The autogsdoc tool</heading>
<p> <section>
The autogsdoc tool is a command-line utility for parsing ObjectiveC <heading>overview</heading>
source code (header files and optionally source files) in order to <p>
generate documentation covering the public interface of the various The autogsdoc tool is a command-line utility for parsing ObjectiveC
classes, categories, and protocols in the source. source code (header files and optionally source files) in order to
</p> generate documentation covering the public interface of the various
<p> classes, categories, and protocols in the source.
The simple way to use this is to run the command with one or more </p>
header file names as arguments ... the tool will automatically <p>
parse corresponding source files in the same directory as the The simple way to use this is to run the command with one or more
headers (or the current directory, or the directory specified header file names as arguments ... the tool will automatically
using the DocumentationDirectory default), and produce gsdoc parse corresponding source files in the same directory as the
and html files as output. headers (or the current directory, or the directory specified
</p> using the DocumentationDirectory default), and produce gsdoc
<p> and html files as output.
Even without any human assistance, this tool will produce skeleton </p>
documents listing the methods in the classes found in the source <p>
files, but more importantly it can take specially formatted comments Even without any human assistance, this tool will produce skeleton
from the source files and insert those comments into the gsdoc output. documents listing the methods in the classes found in the source
</p> files, but more importantly it can take specially formatted comments
<p> from the source files and insert those comments into the gsdoc output.
Any comment beginning with slash and <em>two</em> asterisks rather than </p>
the common slash and single asterisk, is taken to be gsdoc markup, to <p>
be use as the description of the class or method following it. This Any comment beginning with slash and <em>two</em> asterisks rather than
comment text is reformatted and then inserted into the output.<br /> the common slash and single asterisk, is taken to be gsdoc markup, to
Where multiple comments are associatd with the same item, they are be use as the description of the class or method following it. This
joined together with a line break (&lt;br /&gt;) between each if comment text is reformatted and then inserted into the output.<br />
necessary. Where multiple comments are associatd with the same item, they are
</p> joined together with a line break (&lt;br /&gt;) between each if
<p> necessary.
The tool can easily be used to document programs as well as libraries, </p>
simply by giving it the name of the source file containing the main() <p>
function of the program - it takes the special comments from that The tool can easily be used to document programs as well as libraries,
function and handles them specially, inserting them as a section at simply by giving it the name of the source file containing the main()
the end of the first chapter of the document (it creates the first function of the program - it takes the special comments from that
chapter if necessary). function and handles them specially, inserting them as a section at
</p> the end of the first chapter of the document (it creates the first
<p> chapter if necessary).
There are some cases where special extra processing is performed, </p>
predominantly in the first comment found in the source file, </section>
from which various chunks of gsdoc markup may be extracted and <section>
placed into appropriate locations in the output document - <heading>Extra markup</heading>
</p> <p>
<list> There are some cases where special extra processing is performed,
<item><strong>AutogsdocSource</strong> predominantly in the first comment found in the source file,
In any line where <code>AutogsdocSource</code>: is found, the remainder from which various chunks of gsdoc markup may be extracted and
of the line is taken as a source file name to be used instead of placed into appropriate locations in the output document -
making the assumption that each .h file processed uses a .m file </p>
of the same name. You may supply multiple <code>AutogsdocSource</code>: <list>
lines where a header file declares items which are defined in <item><strong>AutogsdocSource</strong>
multiple source files.<br /> In any line where <code>AutogsdocSource</code>: is found, the remainder
If a file name is absolute, it is used just as supplied.<br /> of the line is taken as a source file name to be used instead of
If on the other hand, it is a relative path, the software looks for making the assumption that each .h file processed uses a .m file
the source file first relative to the location of the header file, of the same name. You may supply multiple <code>AutogsdocSource</code>:
and if not found there, relative to the current directory in which lines where a header file declares items which are defined in
autogsdoc is running, and finally relative to the directory multiple source files.<br />
specified by the DocumentationDirectory default. If a file name is absolute, it is used just as supplied.<br />
</item> If on the other hand, it is a relative path, the software looks for
<item><strong>&lt;abstract&gt;</strong> the source file first relative to the location of the header file,
An abstract of the content of the document ... placed in the head and if not found there, relative to the current directory in which
of the gsdoc output. autogsdoc is running, and finally relative to the directory
</item> specified by the DocumentationDirectory default.
<item><strong>&lt;author&gt;</strong> </item>
A description of the author of the code - may be repeated to handle <item><strong>&lt;abstract&gt;</strong>
the case where a document has multiple authors. Placed in the An abstract of the content of the document ... placed in the head
head of the gsdoc output.<br /> of the gsdoc output.
As an aid to readability of the source, some special additional </item>
processing is performed related to the document author -<br /> <item><strong>&lt;author&gt;</strong>
Any line of the form '<code>Author</code>: name &lt;email-address&gt;', A description of the author of the code - may be repeated to handle
or '<code>By</code>: name &lt;email-address&gt;', the case where a document has multiple authors. Placed in the
or '<code>Author</code>: name' or '<code>By</code>: name' head of the gsdoc output.<br />
will be recognised and converted to an <em>author</em> element, As an aid to readability of the source, some special additional
possibly containing an <em>email</em> element. processing is performed related to the document author -<br />
</item> Any line of the form '<code>Author</code>: name &lt;email-address&gt;',
<item><strong>&lt;back&gt;</strong> or '<code>By</code>: name &lt;email-address&gt;',
Placed in the gsdoc output just before the end of the body of the or '<code>Author</code>: name' or '<code>By</code>: name'
document - intended to be used for appendices, index etc. will be recognised and converted to an <em>author</em> element,
</item> possibly containing an <em>email</em> element.
<item><strong>&lt;chapter&gt;</strong> </item>
Placed immediately before any generated class documentation ... <item><strong>&lt;back&gt;</strong>
intended to be used to provide overall description of how the Placed in the gsdoc output just before the end of the body of the
code being documented works.<br />Any documentation for the main() document - intended to be used for appendices, index etc.
function of a program is inserted as a section at the end of this </item>
chapter. <item><strong>&lt;chapter&gt;</strong>
</item> Placed immediately before any generated class documentation ...
<item><strong>&lt;copy&gt;</strong> intended to be used to provide overall description of how the
Copyright of the content of the document ... placed in the head code being documented works.<br />Any documentation for the main()
of the gsdoc output.<br /> function of a program is inserted as a section at the end of this
As an aid to readability of the source, some special additional chapter.
processing is performed -<br /> </item>
Any line of the form 'Copyright (C) text' will be recognised and <item><strong>&lt;copy&gt;</strong>
converted to a <em>copy</em> element. Copyright of the content of the document ... placed in the head
</item> of the gsdoc output.<br />
<item><strong>&lt;date&gt;</strong> As an aid to readability of the source, some special additional
Date of the revision of the document ... placed in the head processing is performed -<br />
of the gsdoc output. If this is omitted the tool will try to Any line of the form 'Copyright (C) text' will be recognised and
construct a value from the RCS Date tag (if available). converted to a <em>copy</em> element.
</item> </item>
<item><strong>&lt;front&gt;</strong> <item><strong>&lt;date&gt;</strong>
Inserted into the document at the start of the body ... intended Date of the revision of the document ... placed in the head
to provide for introduction or contents pages etc. of the gsdoc output. If this is omitted the tool will try to
</item> construct a value from the RCS Date tag (if available).
<item><strong>&lt;title&gt;</strong> </item>
Title of the document ... placed in the head of the gsdoc output. <item><strong>&lt;front&gt;</strong>
If this is omitted the tool will generate a (probably poor) Inserted into the document at the start of the body ... intended
title of its own - so you should include this markup manually. to provide for introduction or contents pages etc.
</item> </item>
<item> <item><strong>&lt;title&gt;</strong>
<strong>NB</strong>This markup may be used within Title of the document ... placed in the head of the gsdoc output.
class, category, or protocol documentation ... if so, it is If this is omitted the tool will generate a (probably poor)
extracted and wrapped round the rest of the documentation for title of its own - so you should include this markup manually.
the class as the classes chapter. </item>
The rest of the class documentation is normally <item>
inserted at the end of the chapter, but may instead be substituted <strong>NB</strong>This markup may be used within
in in place of the &lt;unit /&gt; pseudo-element within the class, category, or protocol documentation ... if so, it is
&lt;chapter&gt; element. extracted and wrapped round the rest of the documentation for
</item> the class as the classes chapter.
<item><strong>&lt;version&gt;</strong> The rest of the class documentation is normally
Version identifier of the document ... placed in the head inserted at the end of the chapter, but may instead be substituted
of the gsdoc output. If this is omitted the tool will try to in in place of the &lt;unit /&gt; pseudo-element within the
construct a value from the RCS Revision tag (if available). &lt;chapter&gt; element.
</item> </item>
</list> <item><strong>&lt;version&gt;</strong>
<p> Version identifier of the document ... placed in the head
In comments being used to provide text for a method description, the of the gsdoc output. If this is omitted the tool will try to
following markup is removed from the text and handled specially - construct a value from the RCS Revision tag (if available).
</p> </item>
<list> </list>
<item><strong>&lt;init /&gt;</strong> </section>
The method is marked as being the designated initialiser for the class. <section>
</item> <heading>Method markup</heading>
<item><strong>&lt;override-subclass /&gt;</strong> <p>
The method is marked as being one which subclasses must override In comments being used to provide text for a method description, the
(eg an abstract method). following markup is removed from the text and handled specially -
</item> </p>
<item><strong>&lt;override-never /&gt;</strong> <list>
The method is marked as being one which subclasses should <em>NOT</em> <item><strong>&lt;init /&gt;</strong>
override. The method is marked as being the designated initialiser for the class.
</item> </item>
<item><strong>&lt;standards&gt; ... &lt;/standards&gt;</strong> <item><strong>&lt;override-subclass /&gt;</strong>
The markup is removed from the description and placed <em>after</em> The method is marked as being one which subclasses must override
it in the gsdoc output - so that the method is described as (eg an abstract method).
conforming (or not conforming) to the specified standards. </item>
</item> <item><strong>&lt;override-never /&gt;</strong>
</list> The method is marked as being one which subclasses should <em>NOT</em>
<p> override.
Generally, the text in comments is reformatted to standardise and </item>
indent it nicely ... the reformatting is <em>not</em> performed on <item><strong>&lt;standards&gt; ... &lt;/standards&gt;</strong>
any text inside an &lt;example&gt; element.<br /> The markup is removed from the description and placed <em>after</em>
When the text is reformatted, it is broken into whitespace separated it in the gsdoc output - so that the method is described as
'words' which are then subjected to some extra processing ... conforming (or not conforming) to the specified standards.
</p> </item>
<list> </list>
<item>Certain well known constants such as YES, NO, and nil are </section>
enclosed in &lt;code&gt; ... &lt;/code&gt; markup. <section>
</item> <heading>Automated markup</heading>
<item>The names of method arguments within method descriptions are <p>
enclosed in &lt;var&gt; ... &lt;/var&gt; markup. Generally, the text in comments is reformatted to standardise and
</item> indent it nicely ... the reformatting is <em>not</em> performed on
<item>Method names (beginning with a plus or minus) are enclosed any text inside an &lt;example&gt; element.<br />
in &lt;ref...&gt; ... &lt;/ref&gt; markup.<br /> When the text is reformatted, it is broken into whitespace separated
eg. "-init" (without the quotes) would be wrapped in a gsdoc 'words' which are then subjected to some extra processing ...
reference element to point to the init method of the current </p>
class or, if only one known class had an init method, it <list>
would refer to the method of that class. <item>Certain well known constants such as YES, NO, and nil are
<br />Note the fact that the method name must be surrounded by enclosed in &lt;code&gt; ... &lt;/code&gt; markup.
whitespace (though a comma, fullstop, or semicolon at the end </item>
of the specifier will also act as a whitespace terminator). <item>The names of method arguments within method descriptions are
</item> enclosed in &lt;var&gt; ... &lt;/var&gt; markup.
<item>Method specifiers including class names (beginning and ending with </item>
square brackets) are enclosed in &lt;ref...&gt; ... &lt;/ref&gt; markup. <item>Method names (beginning with a plus or minus) are enclosed
<br />eg. <code>[</code>NSObject-init<code>]</code>, in &lt;ref...&gt; ... &lt;/ref&gt; markup.<br />
will create a reference to the init method of NSObject (either the eg. "-init" (without the quotes) would be wrapped in a gsdoc
class proper, or any of its categories), while reference element to point to the init method of the current
<br /><code>[</code>(NSCopying)-copyWithZone:<code>]</code>, creates a class or, if only one known class had an init method, it
reference to a method in the NSCopyIng protocol. would refer to the method of that class.
<br />Note that no spaces must appear between the square brackets <br />Note the fact that the method name must be surrounded by
in these specifiers. whitespace to be recognized (though a comma, fullstop, or semicolon
<br />Protocol names are enclosed in round brackets rather than at the end of the specifier will act like whitespace).
the customary angle brackets, because gsdoc is an XML language, and </item>
XML treats angle brackets specially. <item>Method specifiers including class names (beginning and ending with
</item> square brackets) are enclosed in &lt;ref...&gt; ... &lt;/ref&gt; markup.
<item>Function names (ending with '()') other than 'main()' are enclosed <br />eg. <code>[</code>NSObject-init<code>]</code>,
in &lt;ref...&gt; ... &lt;/ref&gt; markup.<br /> will create a reference to the init method of NSObject (either the
eg. "NSLogv()" (without the quotes) would be wrapped in a gsdoc class proper, or any of its categories), while
reference element to point to the documentation of the NSLog function. <br /><code>[</code>(NSCopying)-copyWithZone:<code>]</code>, creates a
<br />Note the fact that the function name must be surrounded by reference to a method in the NSCopyIng protocol.
whitespace (though a comma, fullstop, or semicolon at the end <br />Note that no spaces must appear between the square brackets
of the specifier will also act as a whitespace terminator). in these specifiers.
</item> <br />Protocol names are enclosed in round brackets rather than
</list> the customary angle brackets, because gsdoc is an XML language, and
<p> XML treats angle brackets specially.
The tools accepts certain user defaults (which can of course be </item>
supplied as command-line arguments as usual) - <item>Class names (and also protocol and category names) enclosed
</p> in square brackets are also cross referenced.
<list> <br />Protocol names are enclosed in round brackets rather than
<item><strong>Clean</strong> the customary angle brackets, because gsdoc is an XML language, and
If this boolean value is set to YES, then rather than generating XML treats angle brackets specially.
documentation, the tool removes all gsdoc files generated in the </item>
project, and all html files generated from them (as well as any <item>Function names (ending with '()') other than 'main()' are enclosed
which would be generated from gsdoc files listed explicitly), in &lt;ref...&gt; ... &lt;/ref&gt; markup.<br />
and finally removes the project index file.<br /> eg. "NSLogv()" (without the quotes) would be wrapped in a gsdoc
The only exception to this is that template gsdoc files (ie those reference element to point to the documentation of the NSLog function.
specifield using ConstantsTemplate, FunctionsTemplate arguments etc) <br />Note the fact that the function name must be surrounded by
are not deleted unless the CleanTemplates flag is set. whitespace (though a comma, fullstop, or semicolon at the end
</item> of the specifier will also act as a whitespace terminator).
<item><strong>CleanTemplates</strong> </item>
This flag specifies whether template gsdoc files are to be removed </list>
along with other files when the Clean option is specified. </section>
The default is for them not to be removed ... since these templates <section>
may have been produced manually and just had data inserted into them. <heading>Arguments and Defaults</heading>
</item> <p>
<item><strong>ConstantsTemplate</strong> The tools accepts certain user defaults (which can of course be
Specify the name of a template document into which documentation supplied as command-line arguments as usual) -
about constants should be inserted from all files in the project.<br /> </p>
This is useful if constants in the source code are scattered around many <list>
files, and you need to group them into one place.<br /> <item><strong>Clean</strong>
You are responsible for ensuring that the basic template document If this boolean value is set to YES, then rather than generating
(into which individual constant documentation is inserted) contains documentation, the tool removes all gsdoc files generated in the
all the other information you want, but as a convenience autogsdoc project, and all html files generated from them (as well as any
will generate a simple template (which you may then edit) for you which would be generated from gsdoc files listed explicitly),
if the file does not exist. and finally removes the project index file.<br />
<br />Insertion takes place immediately before the <em>back</em> The only exception to this is that template gsdoc files (ie those
element (or if that does not exist, immediately before the end specifield using "-ConstantsTemplate ...", "-FunctionsTemplate ..."
of the <em>body</em> element) in the template. arguments etc) are not deleted unless the CleanTemplates flag is set.
</item> </item>
<item><strong>Declared</strong> <item><strong>CleanTemplates</strong>
Specify where headers are to be documented as being found.<br /> This flag specifies whether template gsdoc files are to be removed
The actual name produced in the documentation is formed by appending along with other files when the Clean option is specified.
the last component of the header file name to the value of this The default is for them not to be removed ... since these templates
default.<br /> may have been produced manually and just had data inserted into them.
If this default is not specified, the full name of the header file </item>
(as supplied on the command line), with the HeaderDirectory <item><strong>ConstantsTemplate</strong>
default prepended, is used.<br /> Specify the name of a template document into which documentation
A typical usage of this might be <code>-Declared Foundation</code> about constants should be inserted from all files in the project.<br />
when generating documentation for the GNUstep base library. This This is useful if constants in the source code are scattered around many
would result in the documentation saying that NSString is declared files, and you need to group them into one place.<br />
in <code>Foundation/NSString.h</code> You are responsible for ensuring that the basic template document
</item> (into which individual constant documentation is inserted) contains
<item><strong>DocumentAllInstanceVariables</strong> all the other information you want, but as a convenience autogsdoc
This flag permits you to generate documentation for all instance will generate a simple template (which you may then edit) for you
variables. Normally, only those explicitly declared 'public' or if the file does not exist.
'protected' will be documented. <br />Insertion takes place immediately before the <em>back</em>
</item> element (or if that does not exist, immediately before the end
<item><strong>DocumentationDirectory</strong> of the <em>body</em> element) in the template.
May be used to specify the directory in which generated </item>
documentation is to be placed. If this is not set, output <item><strong>Declared</strong>
is placed in the current directory. This directory is also Specify where headers are to be documented as being found.<br />
used as a last resort to locate source files (not headers). The actual name produced in the documentation is formed by appending
</item> the last component of the header file name to the value of this
<item><strong>Files</strong> default.<br />
Specifies the name of a file containing a list of file names as If this default is not specified, the full name of the header file
a property list array <em>(name1,name2,...)</em> format. If this (as supplied on the command line), with the HeaderDirectory
is present, filenames in the program argument list are ignored and default prepended, is used.<br />
the names in this file are used as the list of names to process. A typical usage of this might be <code>"-Declared Foundation"</code>
</item> when generating documentation for the GNUstep base library. This
<item><strong>FunctionsTemplate</strong> would result in the documentation saying that NSString is declared
Specify the name of a template document into which documentation in <code>Foundation/NSString.h</code>
about functions should be inserted from all files in the project.<br /> </item>
This is useful if function source code is scattered around many <item><strong>DocumentAllInstanceVariables</strong>
files, and you need to group it into one place.<br /> This flag permits you to generate documentation for all instance
You are responsible for ensuring that the basic template document variables. Normally, only those explicitly declared 'public' or
(into which individual function documentation is inserted) contains 'protected' will be documented.
all the other information you want, but as a convenience autogsdoc </item>
will generate a simple template (which you may then edit) for you <item><strong>DocumentationDirectory</strong>
if the file does not exist. May be used to specify the directory in which generated
<br />Insertion takes place immediately before the <em>back</em> documentation is to be placed. If this is not set, output
element (or if that does not exist, immediately before the end is placed in the current directory. This directory is also
of the <em>body</em> element) in the template. used as a last resort to locate source files (not headers).
</item> </item>
<item><strong>GenerateHtml</strong> <item><strong>Files</strong>
May be used to specify if HTML output is to be generated. Specifies the name of a file containing a list of file names as
Defaults to YES. a property list array <em>(name1,name2,...)</em> format. If this
</item> is present, filenames in the program argument list are ignored and
<item><strong>HeaderDirectory</strong> the names in this file are used as the list of names to process.
May be used to specify the directory to be searched for header files. </item>
When supplied, this value is prepended to relative header names, <item><strong>FunctionsTemplate</strong>
otherwise the relative header names are interpreted relative to Specify the name of a template document into which documentation
the current directory.<br /> about functions should be inserted from all files in the project.<br />
Header files specified as absolute paths are not influenced by this This is useful if function source code is scattered around many
default. files, and you need to group it into one place.<br />
</item> You are responsible for ensuring that the basic template document
<item><strong>IgnoreDependencies</strong> (into which individual function documentation is inserted) contains
A boolean value which may be used to specify that the program should all the other information you want, but as a convenience autogsdoc
ignore file modification times and regenerate files anyway. Provided will generate a simple template (which you may then edit) for you
for use in conjunction with the <code>make</code> system, which is if the file does not exist.
expected to manage dependency checking itsself. <br />Insertion takes place immediately before the <em>back</em>
</item> element (or if that does not exist, immediately before the end
<item><strong>LocalProjects</strong> of the <em>body</em> element) in the template.
This value is used to control the automatic inclusion of local </item>
external projects into the indexing system for generation of <item><strong>GenerateHtml</strong>
cross-references in final document output.<br /> May be used to specify if HTML output is to be generated.
If set to 'None', then no local project references are done, Defaults to YES.
otherwise, the 'Local' GNUstep documentation directory is recursively </item>
searched for files with a <code>.igsdoc</code> extension, and the <item><strong>HeaderDirectory</strong>
indexing information from those files is used.<br /> May be used to specify the directory to be searched for header files.
The value of this string is also used to generate the filenames in When supplied, this value is prepended to relative header names,
the cross reference ... if it is an empty string, the path to use otherwise the relative header names are interpreted relative to
is assumed to be a file in the same directory where the igsdoc the current directory.<br />
file was found, otherwise it is used as a prefix to the name in Header files specified as absolute paths are not influenced by this
the index.<br /> default.
NB. Local projects with the same name as the project currently </item>
being documented will <em>not</em> be included by this mechanism. <item><strong>IgnoreDependencies</strong>
If you wish to include such projects, you must do so explicitly A boolean value which may be used to specify that the program should
using <em>-Projects</em> ignore file modification times and regenerate files anyway. Provided
</item> for use in conjunction with the <code>make</code> system, which is
<item><strong>MacrosTemplate</strong> expected to manage dependency checking itsself.
Specify the name of a template document into which documentation </item>
about macros should be inserted from all files in the project.<br /> <item><strong>LocalProjects</strong>
This is useful if macro code is scattered around many This value is used to control the automatic inclusion of local
files, and you need to group it into one place.<br /> external projects into the indexing system for generation of
You are responsible for ensuring that the basic template document cross-references in final document output.<br />
(into which individual macro documentation is inserted) contains If set to 'None', then no local project references are done,
all the other information you want, but as a convenience autogsdoc otherwise, the 'Local' GNUstep documentation directory is recursively
will generate a simple template (which you may then edit) for you searched for files with a <code>.igsdoc</code> extension, and the
if the file does not exist. indexing information from those files is used.<br />
<br />Insertion takes place immediately before the <em>back</em> The value of this string is also used to generate the filenames in
element (or if that does not exist, immediately before the end the cross reference ... if it is an empty string, the path to use
of the <em>body</em> element) in the template. is assumed to be a file in the same directory where the igsdoc
</item> file was found, otherwise it is used as a prefix to the name in
<item><strong>Project</strong> the index.<br />
May be used to specify the name of this project ... determines the NB. Local projects with the same name as the project currently
name of the index reference file produced as part of the documentation being documented will <em>not</em> be included by this mechanism.
to provide information enabling other projects to cross-reference to If you wish to include such projects, you must do so explicitly
items in this project. using <em>"-Projects ..."</em>
</item> </item>
<item><strong>Projects</strong> <item><strong>MacrosTemplate</strong>
This value may be supplied as a dictionary containing the paths to Specify the name of a template document into which documentation
the igsdoc index/reference files used by external projects, along about macros should be inserted from all files in the project.<br />
with values to be used to map the filenames found in the indexes.<br /> This is useful if macro code is scattered around many
For example, if a project index (igsdoc) file says that the class files, and you need to group it into one place.<br />
<code>Foo</code> is found in the file <code>Foo</code>, and the You are responsible for ensuring that the basic template document
path associated with that project index is <code>/usr/doc/proj</code>, (into which individual macro documentation is inserted) contains
Then generated html output may reference the class as being in all the other information you want, but as a convenience autogsdoc
<code>/usr/doc/prj/Foo.html</code> will generate a simple template (which you may then edit) for you
</item> if the file does not exist.
<item><strong>ShowDependencies</strong> <br />Insertion takes place immediately before the <em>back</em>
A boolean value which may be used to specify that the program should element (or if that does not exist, immediately before the end
log which files are being regenerated because of their dependencies of the <em>body</em> element) in the template.
on other files. </item>
</item> <item><strong>Project</strong>
<item><strong>Standards</strong> May be used to specify the name of this project ... determines the
A boolean value used to specify whether the program should insert name of the index reference file produced as part of the documentation
information about standards complience into ythe documentation. to provide information enabling other projects to cross-reference to
This should only be used when documenting the GNUstep libraries items in this project.
and tools themselves as it assumes that the code being documented </item>
is part of GNUstep and possibly complies with the OpenStep standard <item><strong>Projects</strong>
or implements MacOS-X compatible methods. This value may be supplied as a dictionary containing the paths to
</item> the igsdoc index/reference files used by external projects, along
<item><strong>SystemProjects</strong> with values to be used to map the filenames found in the indexes.<br />
This value is used to control the automatic inclusion of system For example, if a project index (igsdoc) file says that the class
external projects into the indexing system for generation of <code>Foo</code> is found in the file <code>Foo</code>, and the
cross-references in final document output.<br /> path associated with that project index is <code>/usr/doc/proj</code>,
If set to 'None', then no system project references are done, Then generated html output may reference the class as being in
otherwise, the 'System' GNUstep documentation directory is recursively <code>/usr/doc/prj/Foo.html</code>
searched for files with a <code>.igsdoc</code> extension, and the </item>
indexing information from those files is used.<br /> <item><strong>ShowDependencies</strong>
The value of this string is also used to generate the filenames in A boolean value which may be used to specify that the program should
the cross reference ... if it is an empty string, the path to use log which files are being regenerated because of their dependencies
is assumed to be a file in the same directory where the igsdoc on other files.
file was found, otherwise it is used as a prefix to the name in </item>
the index.<br /> <item><strong>Standards</strong>
NB. System projects with the same name as the project currently A boolean value used to specify whether the program should insert
being documented will <em>not</em> be included by this mechanism. information about standards complience into ythe documentation.
If you wish to include such projects, you must do so explicitly This should only be used when documenting the GNUstep libraries
using <em>-Projects</em> and tools themselves as it assumes that the code being documented
</item> is part of GNUstep and possibly complies with the OpenStep standard
<item><strong>TypedefsTemplate</strong> or implements MacOS-X compatible methods.
Specify the name of a template document into which documentation </item>
about typedefs should be inserted from all files in the project.<br /> <item><strong>SystemProjects</strong>
This is useful if typedef source code is scattered around many This value is used to control the automatic inclusion of system
files, and you need to group it into one place.<br /> external projects into the indexing system for generation of
You are responsible for ensuring that the basic template document cross-references in final document output.<br />
(into which individual typedef documentation is inserted) contains If set to 'None', then no system project references are done,
all the other information you want, but as a convenience autogsdoc otherwise, the 'System' GNUstep documentation directory is recursively
will generate a simple template (which you may then edit) for you searched for files with a <code>.igsdoc</code> extension, and the
if the file does not exist. indexing information from those files is used.<br />
<br />Insertion takes place immediately before the <em>back</em> The value of this string is also used to generate the filenames in
element (or if that does not exist, immediately before the end the cross reference ... if it is an empty string, the path to use
of the <em>body</em> element) in the template. is assumed to be a file in the same directory where the igsdoc
</item> file was found, otherwise it is used as a prefix to the name in
<item><strong>Up</strong> the index.<br />
A string used to supply the name to be used in the 'up' link from NB. System projects with the same name as the project currently
generated gsdoc documents. This should normally be the name of a being documented will <em>not</em> be included by this mechanism.
file which contains an index of the contents of a project.<br /> If you wish to include such projects, you must do so explicitly
If this is missing or set to an empty string, then no 'up' link using <em>"-Projects ..."</em>
will be provided in the documents. </item>
</item> <item><strong>TypedefsTemplate</strong>
<item><strong>VariablesTemplate</strong> Specify the name of a template document into which documentation
Specify the name of a template document into which documentation about typedefs should be inserted from all files in the project.<br />
about variables should be inserted from all files in the project.<br /> This is useful if typedef source code is scattered around many
This is useful if variable source code is scattered around many files, and you need to group it into one place.<br />
files, and you need to group it into one place.<br /> You are responsible for ensuring that the basic template document
You are responsible for ensuring that the basic template document (into which individual typedef documentation is inserted) contains
(into which individual variable documentation is inserted) contains all the other information you want, but as a convenience autogsdoc
all the other information you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) for you
will generate a simple template (which you may then edit) for you if the file does not exist.
if the file does not exist. <br />Insertion takes place immediately before the <em>back</em>
<br />Insertion takes place immediately before the <em>back</em> element (or if that does not exist, immediately before the end
element (or if that does not exist, immediately before the end of the <em>body</em> element) in the template.
of the <em>body</em> element) in the template. </item>
</item> <item><strong>Up</strong>
<item><strong>Verbose</strong> A string used to supply the name to be used in the 'up' link from
A boolean used to specify whether you want verbose debug/warning generated gsdoc documents. This should normally be the name of a
output to be produced. file which contains an index of the contents of a project.<br />
</item> If this is missing or set to an empty string, then no 'up' link
<item><strong>Warn</strong> will be provided in the documents.
A boolean used to specify whether you want standard warning </item>
output (eg report of undocumented methods) produced. <item><strong>VariablesTemplate</strong>
</item> Specify the name of a template document into which documentation
<item><strong>WordMap</strong> about variables should be inserted from all files in the project.<br />
This value is a dictionary used to map identifiers/keywords found This is useful if variable source code is scattered around many
in the source files to other words. Generally you will not have files, and you need to group it into one place.<br />
to use this, but it is sometimes helpful to avoid the parser being You are responsible for ensuring that the basic template document
confused by the use of C preprocessor macros. You can effectively (into which individual variable documentation is inserted) contains
redefine the macro to something less confusing.<br /> all the other information you want, but as a convenience autogsdoc
The value you map the identifier to must be one of -<br /> will generate a simple template (which you may then edit) for you
Another identifier,<br /> if the file does not exist.
An empty string - the value is ignored,<br /> <br />Insertion takes place immediately before the <em>back</em>
Two slashes ('//') - the rest of the line is ignored.<br /> element (or if that does not exist, immediately before the end
</item> of the <em>body</em> element) in the template.
</list> </item>
<item><strong>Verbose</strong>
A boolean used to specify whether you want verbose debug/warning
output to be produced.
</item>
<item><strong>Warn</strong>
A boolean used to specify whether you want standard warning
output (eg report of undocumented methods) produced.
</item>
<item><strong>WordMap</strong>
This value is a dictionary used to map identifiers/keywords found
in the source files to other words. Generally you will not have
to use this, but it is sometimes helpful to avoid the parser being
confused by the use of C preprocessor macros. You can effectively
redefine the macro to something less confusing.<br />
The value you map the identifier to must be one of -<br />
Another identifier,<br />
An empty string - the value is ignored,<br />
Two slashes ('//') - the rest of the line is ignored.<br />
</item>
</list>
</section>
<section> <section>
<heading>Inter-document linkage</heading> <heading>Inter-document linkage</heading>
<p> <p>

2
Tools/gsdoc-1_0_0.dtd
View file

@ -149,7 +149,7 @@
<!ELEMENT ref (%text;)*> <!ELEMENT ref (%text;)*>
<!ATTLIST ref <!ATTLIST ref
id CDATA #REQUIRED id CDATA #REQUIRED
type (class|protocol|method|ivariable|function|type|macro|variable|constant|label|EOModel|EOEntity) "label" type (class|category|protocol|method|ivariable|function|type|macro|variable|constant|label|EOModel|EOEntity) "label"
class CDATA #IMPLIED class CDATA #IMPLIED
> >