diff --git a/Headers/gnustep/base/NSObject.h b/Headers/gnustep/base/NSObject.h index 2a3403036..f67d2845b 100644 --- a/Headers/gnustep/base/NSObject.h +++ b/Headers/gnustep/base/NSObject.h @@ -189,7 +189,7 @@ * class of the object to be aClass etc. The allocated memory will * be extraBytes larger than the space actually needed to hold the * instance variables of the object.
- * This function is used by the [NSObject-allocWithZone:] mnethod. + * This function is used by the [NSObject+allocWithZone:] mnethod. */ GS_EXPORT NSObject * NSAllocateObject(Class aClass, unsigned extraBytes, NSZone *zone); @@ -206,7 +206,8 @@ NSDeallocateObject(NSObject *anObject); * memory allocated from zone. The allocated memory will be extraBytes * longer than that necessary to actually store the instance variables * of the copied object.
- * This is used by the [NSObject-copyWithZone:] method. + * This is used by the NSObject implementation of the + * [(NSCopying)-copyWithZone:] method. */ GS_EXPORT NSObject * NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone); diff --git a/Source/NSObjCRuntime.m b/Source/NSObjCRuntime.m index e9f1f8500..6716686c4 100644 --- a/Source/NSObjCRuntime.m +++ b/Source/NSObjCRuntime.m @@ -510,7 +510,7 @@ GSGetValue(NSObject *self, NSString *key, SEL sel, * supplied).
* Automatic conversion between NSNumber and C scalar types is performed.
* 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. */ void diff --git a/Tools/AGSHtml.m b/Tools/AGSHtml.m index 965249ad5..57ac5d48c 100644 --- a/Tools/AGSHtml.m +++ b/Tools/AGSHtml.m @@ -188,8 +188,8 @@ static NSMutableSet *textNodes = nil; if (u == nil) { u = unit; + s = base; } - s = base; } else if (u == nil) { @@ -215,7 +215,7 @@ static NSMutableSet *textNodes = nil; s = [globalRefs unitRef: r type: t unit: &u]; } } - else + if (s == nil) { NSString *tmp = u; @@ -1448,12 +1448,12 @@ static NSMutableSet *textNodes = nil; NSString *type = [prop objectForKey: @"type"]; NSString *r = [prop objectForKey: @"id"]; GSXMLNode *tmp = [node firstChild]; + NSString *c = [prop objectForKey: @"class"]; NSString *s; if ([type isEqual: @"method"] || [type isEqual: @"ivariable"]) { - s = [prop objectForKey: @"class"]; - s = [self makeLink: r ofType: type inUnit: s isRef: YES]; + s = [self makeLink: r ofType: type inUnit: c isRef: YES]; } else { @@ -1470,7 +1470,16 @@ static NSMutableSet *textNodes = 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) { [buf appendString: r]; diff --git a/Tools/AGSOutput.m b/Tools/AGSOutput.m index 5a51a6c69..bf60056ed 100644 --- a/Tools/AGSOutput.m +++ b/Tools/AGSOutput.m @@ -69,6 +69,11 @@ static BOOL snuggleStart(NSString *t) * far too special purpose.

* *

Here is the afterword for the class.

+ *

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)]. + *

* * And finally, here is the actual class description ... outside the chapter. * With a reference to foo() in it. @@ -1809,6 +1814,7 @@ static BOOL snuggleStart(NSString *t) /* * Ensure that methods are rendered as references. * First look for format with class name in square brackets. + * If that's all there is, we make a class reference. */ r = [tmp rangeOfString: @"["]; if (r.length > 0) @@ -1824,6 +1830,7 @@ static BOOL snuggleStart(NSString *t) NSString *cName = nil; NSString *mName = nil; unichar c; + BOOL isProtocol = NO; if (pos < ePos && [identStart characterIsMember: @@ -1880,8 +1887,7 @@ static BOOL snuggleStart(NSString *t) cName = [tmp substringWithRange: r]; } } - else if (pos < ePos - && (c = [tmp characterAtIndex: pos]) == '(') + else if (pos < ePos && (c = [tmp characterAtIndex: pos]) == '(') { /* * Look for protocol name. @@ -1903,6 +1909,7 @@ static BOOL snuggleStart(NSString *t) } pos++; } + isProtocol = YES; } if (pos < ePos && (c == '+' || c == '-')) @@ -1986,6 +1993,23 @@ static BOOL snuggleStart(NSString *t) ref = [NSString stringWithFormat: @"", mName]; } + else if (isProtocol == YES) + { + ref = [NSString stringWithFormat: + @"", + mName, cName]; + if (isProtocol == YES) + { + if (sub == nil) + { + sub = tmp; + } + sub = [sub stringByReplacingString: @"(" + withString: @"<"]; + sub = [sub stringByReplacingString: @")" + withString: @">"]; + } + } else { ref = [NSString stringWithFormat: @@ -2005,6 +2029,34 @@ static BOOL snuggleStart(NSString *t) [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: + @"<%@>", + cName, cName]; + } + else if ([cName hasSuffix: @")"] == YES) + { + ref = [NSString stringWithFormat: + @"%@", + cName, cName]; + } + else + { + ref = [NSString stringWithFormat: + @"%@", + cName, cName]; + } + [a replaceObjectAtIndex: l withObject: ref]; + } } continue; } diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index 64daccb96..648310537 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -20,428 +20,449 @@ The autogsdoc tool -

- The autogsdoc tool is a command-line utility for parsing ObjectiveC - source code (header files and optionally source files) in order to - generate documentation covering the public interface of the various - classes, categories, and protocols in the source. -

-

- The simple way to use this is to run the command with one or more - header file names as arguments ... the tool will automatically - parse corresponding source files in the same directory as the - headers (or the current directory, or the directory specified - using the DocumentationDirectory default), and produce gsdoc - and html files as output. -

-

- Even without any human assistance, this tool will produce skeleton - documents listing the methods in the classes found in the source - files, but more importantly it can take specially formatted comments - from the source files and insert those comments into the gsdoc output. -

-

- Any comment beginning with slash and two asterisks rather than - the common slash and single asterisk, is taken to be gsdoc markup, to - be use as the description of the class or method following it. This - comment text is reformatted and then inserted into the output.
- Where multiple comments are associatd with the same item, they are - joined together 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 that - function and handles them specially, inserting them as a section at - the end of the first chapter of the document (it creates the first - chapter if necessary). -

-

- There are some cases where special extra processing is performed, - predominantly in the first comment found in the source file, - from which various chunks of gsdoc markup may be extracted and - placed into appropriate locations in the output document - -

- - AutogsdocSource - In any line where AutogsdocSource: is found, the remainder - of the line is taken as a source file name to be used instead of - making the assumption that each .h file processed uses a .m file - of the same name. You may supply multiple AutogsdocSource: - lines where a header file declares items which are defined in - multiple source files.
- If a file name is absolute, it is used just as supplied.
- If on the other hand, it is a relative path, the software looks for - the source file first relative to the location of the header file, - and if not found there, relative to the current directory in which - autogsdoc is running, and finally relative to the directory - specified by the DocumentationDirectory default. - - <abstract> - An abstract of the content of the document ... placed in the head - of the gsdoc output. - - <author> - A description of the author of the code - may be repeated to handle - the case where a document has multiple authors. Placed in the - head of the gsdoc output.
- As an aid to readability of the source, some special additional - processing 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 an author element, - possibly containing an email element. - - <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 the - code being documented works.
Any documentation for the main() - function of a program is inserted as a section at the end of this - chapter. - - <copy> - Copyright of the content of the document ... placed in the head - of the gsdoc output.
- As an aid to readability of the source, some special additional - processing is performed -
- Any line of the form 'Copyright (C) text' will be recognised and - converted to a copy element. - - <date> - Date of the revision of the document ... placed in the head - of the gsdoc output. If this is omitted the tool will try to - construct a value from the RCS Date tag (if available). - - <front> - Inserted into the document at the start of the body ... intended - to 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. - - - NBThis markup may be used within - class, category, or protocol documentation ... if so, it is - extracted and wrapped round the rest of the documentation for - the class as the classes chapter. - The rest of the class documentation is normally - inserted at the end of the chapter, but may instead be substituted - in in place of the <unit /> pseudo-element within the - <chapter> element. - - <version> - Version identifier of the document ... placed in the head - of the gsdoc output. If this is omitted the tool will try to - construct a value from the RCS Revision tag (if available). - - -

- In comments being used to provide text for a method description, the - following 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 - (eg an abstract method). - - <override-never /> - The method is marked as being one which subclasses should NOT - override. - - <standards> ... </standards> - The markup is removed from the description and placed after - it in the gsdoc output - so that the method is described as - conforming (or not conforming) to the specified standards. - - -

- Generally, the text in comments is reformatted to standardise and - indent it nicely ... the reformatting is not performed on - any text inside an <example> element.
- When the text is reformatted, 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.
- eg. "-init" (without the quotes) would be wrapped in a gsdoc - reference element to point to the init method of the current - class or, if only one known class had an init method, it - would refer to the method of that class. -
Note the fact that the method name must be surrounded by - whitespace (though a comma, fullstop, or semicolon at the end - of the specifier will also act as a whitespace terminator). - - Method specifiers including class names (beginning and ending with - square brackets) are enclosed in <ref...> ... </ref> markup. -
eg. [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 the NSCopyIng protocol. -
Note that no spaces must appear between the square brackets - in these specifiers. -
Protocol names are enclosed in round brackets rather than - the customary angle brackets, because gsdoc is an XML language, and - XML treats angle brackets specially. - - Function names (ending with '()') other than 'main()' are enclosed - in <ref...> ... </ref> markup.
- eg. "NSLogv()" (without the quotes) would be wrapped in a gsdoc - reference element to point to the documentation of the NSLog function. -
Note the fact that the function name must be surrounded by - whitespace (though a comma, fullstop, or semicolon at the end - of the specifier will also act as a whitespace terminator). - - -

- The tools accepts certain user defaults (which can of course be - supplied as command-line arguments as usual) - -

- - Clean - If this boolean value is set to YES, then rather than generating - documentation, the tool removes all gsdoc files generated in the - project, and all html files generated from them (as well as any - which would be generated from gsdoc files listed explicitly), - and finally removes the project index file.
- The only exception to this is that template gsdoc files (ie those - specifield 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 removed - along with other files when the Clean option is specified. - The default is for them not to be removed ... since these templates - may have been produced manually and just had data inserted into them. - - ConstantsTemplate - Specify the name of a template document into which documentation - about constants should be inserted from all files in the project.
- This is useful if constants in the source code are scattered around many - files, 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) contains - all the other information you want, but as a convenience autogsdoc - will generate a simple template (which you may then edit) for you - if the file does not exist. -
Insertion takes place immediately before the back - element (or if that does not exist, immediately before the end - of the body element) in the template. - - Declared - Specify where headers are to be documented as being found.
- The actual name produced in the documentation is formed by appending - the last component of the header file name to the value of this - default.
- If this default is not specified, the full name of the header file - (as supplied on the command line), with the HeaderDirectory - default prepended, is used.
- A typical usage of this might be -Declared Foundation - when generating documentation for the GNUstep base library. This - would result in the documentation saying that NSString is declared - in Foundation/NSString.h - - DocumentAllInstanceVariables - This flag permits you to generate documentation for all instance - variables. Normally, only those explicitly declared 'public' or - 'protected' will be documented. - - DocumentationDirectory - May be used to specify the directory in which generated - documentation is to be placed. If this is not set, output - is placed in the current directory. This directory is also - used as a last resort to locate source files (not headers). - - Files - Specifies the name of a file containing a list of file names as - a property list array (name1,name2,...) format. If this - is present, filenames in the program argument list are ignored 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 documentation - about functions should be inserted from all files in the project.
- This is useful if function source code is scattered around many - files, 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) contains - all the other information you want, but as a convenience autogsdoc - will generate a simple template (which you may then edit) for you - if the file does not exist. -
Insertion takes place immediately before the back - element (or if that does not exist, immediately before the end - of the body element) 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 to - the current directory.
- Header files specified as absolute paths are not influenced by this - default. - - IgnoreDependencies - A boolean value which may be used to specify that the program should - ignore file modification times and regenerate files anyway. Provided - for use in conjunction with the make system, which is - expected to manage dependency checking itsself. - - LocalProjects - This value is used to control the automatic inclusion of local - external projects into the indexing system for generation of - cross-references in final document output.
- If set to 'None', then no local project references are done, - otherwise, the 'Local' GNUstep documentation directory is recursively - searched for files with a .igsdoc extension, and the - indexing information from those files is used.
- The value of this string is also used to generate the filenames in - the cross reference ... if it is an empty string, the path to use - is assumed to be a file in the same directory where the igsdoc - file was found, otherwise it is used as a prefix to the name in - the index.
- NB. Local projects with the same name as the project currently - being documented will not be included by this mechanism. - If you wish to include such projects, you must do so explicitly - using -Projects - - MacrosTemplate - Specify the name of a template document into which documentation - about macros should be inserted from all files in the project.
- This is useful if macro code is scattered around many - files, 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) contains - all the other information you want, but as a convenience autogsdoc - will generate a simple template (which you may then edit) for you - if the file does not exist. -
Insertion takes place immediately before the back - element (or if that does not exist, immediately before the end - of the body element) in the template. - - Project - May be used to specify the name of this project ... determines the - name of the index reference file produced as part of the documentation - to provide information enabling other projects to cross-reference to - items in this project. - - Projects - This value may be supplied as a dictionary containing the paths to - the igsdoc index/reference files used by external projects, along - with 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 the - path 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 - - ShowDependencies - A boolean value which may be used to specify that the program should - log which files are being regenerated because of their dependencies - on other files. - - Standards - A boolean value used to specify whether the program should insert - information about standards complience into ythe documentation. - This should only be used when documenting the GNUstep libraries - and tools themselves as it assumes that the code being documented - is part of GNUstep and possibly complies with the OpenStep standard - or implements MacOS-X compatible methods. - - SystemProjects - This value is used to control the automatic inclusion of system - external projects into the indexing system for generation of - cross-references in final document output.
- If set to 'None', then no system project references are done, - otherwise, the 'System' GNUstep documentation directory is recursively - searched for files with a .igsdoc extension, and the - indexing information from those files is used.
- The value of this string is also used to generate the filenames in - the cross reference ... if it is an empty string, the path to use - is assumed to be a file in the same directory where the igsdoc - file was found, otherwise it is used as a prefix to the name in - the index.
- NB. System projects with the same name as the project currently - being documented will not be included by this mechanism. - If you wish to include such projects, you must do so explicitly - using -Projects - - TypedefsTemplate - Specify the name of a template document into which documentation - about typedefs should be inserted from all files in the project.
- This is useful if typedef source code is scattered around many - files, 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) contains - all the other information you want, but as a convenience autogsdoc - will generate a simple template (which you may then edit) for you - if the file does not exist. -
Insertion takes place immediately before the back - element (or if that does not exist, immediately before the end - of the body element) in the template. - - Up - A string used to supply the name to be used in the 'up' link from - generated gsdoc documents. This should normally be the name of a - file which contains an index of the contents of a project.
- If this is missing or set to an empty string, then no 'up' link - will be provided in the documents. - - VariablesTemplate - Specify the name of a template document into which documentation - about variables should be inserted from all files in the project.
- This is useful if variable source code is scattered around many - files, 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) contains - all the other information you want, but as a convenience autogsdoc - will generate a simple template (which you may then edit) for you - if the file does not exist. -
Insertion takes place immediately before the back - element (or if that does not exist, immediately before the end - of the body element) in the template. - - Verbose - A boolean used to specify whether you want verbose debug/warning - output to be produced. - - Warn - A boolean used to specify whether you want standard warning - output (eg report of undocumented methods) produced. - - WordMap - 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.
- 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.
- - +
+ overview +

+ The autogsdoc tool is a command-line utility for parsing ObjectiveC + source code (header files and optionally source files) in order to + generate documentation covering the public interface of the various + classes, categories, and protocols in the source. +

+

+ The simple way to use this is to run the command with one or more + header file names as arguments ... the tool will automatically + parse corresponding source files in the same directory as the + headers (or the current directory, or the directory specified + using the DocumentationDirectory default), and produce gsdoc + and html files as output. +

+

+ Even without any human assistance, this tool will produce skeleton + documents listing the methods in the classes found in the source + files, but more importantly it can take specially formatted comments + from the source files and insert those comments into the gsdoc output. +

+

+ Any comment beginning with slash and two asterisks rather than + the common slash and single asterisk, is taken to be gsdoc markup, to + be use as the description of the class or method following it. This + comment text is reformatted and then inserted into the output.
+ Where multiple comments are associatd with the same item, they are + joined together 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 that + function and handles them specially, inserting them as a section at + the end of the first chapter of the document (it creates the first + chapter if necessary). +

+
+
+ Extra markup +

+ There are some cases where special extra processing is performed, + predominantly in the first comment found in the source file, + from which various chunks of gsdoc markup may be extracted and + placed into appropriate locations in the output document - +

+ + AutogsdocSource + In any line where AutogsdocSource: is found, the remainder + of the line is taken as a source file name to be used instead of + making the assumption that each .h file processed uses a .m file + of the same name. You may supply multiple AutogsdocSource: + lines where a header file declares items which are defined in + multiple source files.
+ If a file name is absolute, it is used just as supplied.
+ If on the other hand, it is a relative path, the software looks for + the source file first relative to the location of the header file, + and if not found there, relative to the current directory in which + autogsdoc is running, and finally relative to the directory + specified by the DocumentationDirectory default. + + <abstract> + An abstract of the content of the document ... placed in the head + of the gsdoc output. + + <author> + A description of the author of the code - may be repeated to handle + the case where a document has multiple authors. Placed in the + head of the gsdoc output.
+ As an aid to readability of the source, some special additional + processing 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 an author element, + possibly containing an email element. + + <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 the + code being documented works.
Any documentation for the main() + function of a program is inserted as a section at the end of this + chapter. + + <copy> + Copyright of the content of the document ... placed in the head + of the gsdoc output.
+ As an aid to readability of the source, some special additional + processing is performed -
+ Any line of the form 'Copyright (C) text' will be recognised and + converted to a copy element. + + <date> + Date of the revision of the document ... placed in the head + of the gsdoc output. If this is omitted the tool will try to + construct a value from the RCS Date tag (if available). + + <front> + Inserted into the document at the start of the body ... intended + to 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. + + + NBThis markup may be used within + class, category, or protocol documentation ... if so, it is + extracted and wrapped round the rest of the documentation for + the class as the classes chapter. + The rest of the class documentation is normally + inserted at the end of the chapter, but may instead be substituted + in in place of the <unit /> pseudo-element within the + <chapter> element. + + <version> + Version identifier of the document ... placed in the head + of the gsdoc output. If this is omitted the tool will try to + construct a value from the RCS Revision tag (if available). + + +
+
+ Method markup +

+ In comments being used to provide text for a method description, the + following 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 + (eg an abstract method). + + <override-never /> + The method is marked as being one which subclasses should NOT + override. + + <standards> ... </standards> + The markup is removed from the description and placed after + it in the gsdoc output - so that the method is described as + conforming (or not conforming) to the specified standards. + + +
+
+ Automated markup +

+ Generally, the text in comments is reformatted to standardise and + indent it nicely ... the reformatting is not performed on + any text inside an <example> element.
+ When the text is reformatted, 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.
+ eg. "-init" (without the quotes) would be wrapped in a gsdoc + reference element to point to the init method of the current + class or, if only one known class had an init method, it + would refer to the method of that class. +
Note the fact that the method name must be surrounded by + whitespace to be recognized (though a comma, fullstop, or semicolon + at the end of the specifier will act like whitespace). + + Method specifiers including class names (beginning and ending with + square brackets) are enclosed in <ref...> ... </ref> markup. +
eg. [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 the NSCopyIng protocol. +
Note that no spaces must appear between the square brackets + in these specifiers. +
Protocol names are enclosed in round brackets rather than + the customary angle brackets, because gsdoc is an XML language, and + XML treats angle brackets specially. + + Class names (and also protocol and category names) enclosed + in square brackets are also cross referenced. +
Protocol names are enclosed in round brackets rather than + the customary angle brackets, because gsdoc is an XML language, and + XML treats angle brackets specially. + + Function names (ending with '()') other than 'main()' are enclosed + in <ref...> ... </ref> markup.
+ eg. "NSLogv()" (without the quotes) would be wrapped in a gsdoc + reference element to point to the documentation of the NSLog function. +
Note the fact that the function name must be surrounded by + whitespace (though a comma, fullstop, or semicolon at the end + of the specifier will also act as a whitespace terminator). + + +
+
+ Arguments and Defaults +

+ The tools accepts certain user defaults (which can of course be + supplied as command-line arguments as usual) - +

+ + Clean + If this boolean value is set to YES, then rather than generating + documentation, the tool removes all gsdoc files generated in the + project, and all html files generated from them (as well as any + which would be generated from gsdoc files listed explicitly), + and finally removes the project index file.
+ The only exception to this is that template gsdoc files (ie those + specifield 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 removed + along with other files when the Clean option is specified. + The default is for them not to be removed ... since these templates + may have been produced manually and just had data inserted into them. + + ConstantsTemplate + Specify the name of a template document into which documentation + about constants should be inserted from all files in the project.
+ This is useful if constants in the source code are scattered around many + files, 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) contains + all the other information you want, but as a convenience autogsdoc + will generate a simple template (which you may then edit) for you + if the file does not exist. +
Insertion takes place immediately before the back + element (or if that does not exist, immediately before the end + of the body element) in the template. + + Declared + Specify where headers are to be documented as being found.
+ The actual name produced in the documentation is formed by appending + the last component of the header file name to the value of this + default.
+ If this default is not specified, the full name of the header file + (as supplied on the command line), with the HeaderDirectory + default prepended, is used.
+ A typical usage of this might be "-Declared Foundation" + when generating documentation for the GNUstep base library. This + would result in the documentation saying that NSString is declared + in Foundation/NSString.h + + DocumentAllInstanceVariables + This flag permits you to generate documentation for all instance + variables. Normally, only those explicitly declared 'public' or + 'protected' will be documented. + + DocumentationDirectory + May be used to specify the directory in which generated + documentation is to be placed. If this is not set, output + is placed in the current directory. This directory is also + used as a last resort to locate source files (not headers). + + Files + Specifies the name of a file containing a list of file names as + a property list array (name1,name2,...) format. If this + is present, filenames in the program argument list are ignored 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 documentation + about functions should be inserted from all files in the project.
+ This is useful if function source code is scattered around many + files, 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) contains + all the other information you want, but as a convenience autogsdoc + will generate a simple template (which you may then edit) for you + if the file does not exist. +
Insertion takes place immediately before the back + element (or if that does not exist, immediately before the end + of the body element) 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 to + the current directory.
+ Header files specified as absolute paths are not influenced by this + default. + + IgnoreDependencies + A boolean value which may be used to specify that the program should + ignore file modification times and regenerate files anyway. Provided + for use in conjunction with the make system, which is + expected to manage dependency checking itsself. + + LocalProjects + This value is used to control the automatic inclusion of local + external projects into the indexing system for generation of + cross-references in final document output.
+ If set to 'None', then no local project references are done, + otherwise, the 'Local' GNUstep documentation directory is recursively + searched for files with a .igsdoc extension, and the + indexing information from those files is used.
+ The value of this string is also used to generate the filenames in + the cross reference ... if it is an empty string, the path to use + is assumed to be a file in the same directory where the igsdoc + file was found, otherwise it is used as a prefix to the name in + the index.
+ NB. Local projects with the same name as the project currently + being documented will not be included by this mechanism. + If you wish to include such projects, you must do so explicitly + using "-Projects ..." + + MacrosTemplate + Specify the name of a template document into which documentation + about macros should be inserted from all files in the project.
+ This is useful if macro code is scattered around many + files, 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) contains + all the other information you want, but as a convenience autogsdoc + will generate a simple template (which you may then edit) for you + if the file does not exist. +
Insertion takes place immediately before the back + element (or if that does not exist, immediately before the end + of the body element) in the template. + + Project + May be used to specify the name of this project ... determines the + name of the index reference file produced as part of the documentation + to provide information enabling other projects to cross-reference to + items in this project. + + Projects + This value may be supplied as a dictionary containing the paths to + the igsdoc index/reference files used by external projects, along + with 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 the + path 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 + + ShowDependencies + A boolean value which may be used to specify that the program should + log which files are being regenerated because of their dependencies + on other files. + + Standards + A boolean value used to specify whether the program should insert + information about standards complience into ythe documentation. + This should only be used when documenting the GNUstep libraries + and tools themselves as it assumes that the code being documented + is part of GNUstep and possibly complies with the OpenStep standard + or implements MacOS-X compatible methods. + + SystemProjects + This value is used to control the automatic inclusion of system + external projects into the indexing system for generation of + cross-references in final document output.
+ If set to 'None', then no system project references are done, + otherwise, the 'System' GNUstep documentation directory is recursively + searched for files with a .igsdoc extension, and the + indexing information from those files is used.
+ The value of this string is also used to generate the filenames in + the cross reference ... if it is an empty string, the path to use + is assumed to be a file in the same directory where the igsdoc + file was found, otherwise it is used as a prefix to the name in + the index.
+ NB. System projects with the same name as the project currently + being documented will not be included by this mechanism. + If you wish to include such projects, you must do so explicitly + using "-Projects ..." + + TypedefsTemplate + Specify the name of a template document into which documentation + about typedefs should be inserted from all files in the project.
+ This is useful if typedef source code is scattered around many + files, 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) contains + all the other information you want, but as a convenience autogsdoc + will generate a simple template (which you may then edit) for you + if the file does not exist. +
Insertion takes place immediately before the back + element (or if that does not exist, immediately before the end + of the body element) in the template. + + Up + A string used to supply the name to be used in the 'up' link from + generated gsdoc documents. This should normally be the name of a + file which contains an index of the contents of a project.
+ If this is missing or set to an empty string, then no 'up' link + will be provided in the documents. + + VariablesTemplate + Specify the name of a template document into which documentation + about variables should be inserted from all files in the project.
+ This is useful if variable source code is scattered around many + files, 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) contains + all the other information you want, but as a convenience autogsdoc + will generate a simple template (which you may then edit) for you + if the file does not exist. +
Insertion takes place immediately before the back + element (or if that does not exist, immediately before the end + of the body element) in the template. + + Verbose + A boolean used to specify whether you want verbose debug/warning + output to be produced. + + Warn + A boolean used to specify whether you want standard warning + output (eg report of undocumented methods) produced. + + WordMap + 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.
+ 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.
+ + +
Inter-document linkage

diff --git a/Tools/gsdoc-1_0_0.dtd b/Tools/gsdoc-1_0_0.dtd index 99add52d2..2438d2ac7 100644 --- a/Tools/gsdoc-1_0_0.dtd +++ b/Tools/gsdoc-1_0_0.dtd @@ -149,7 +149,7 @@