This is AutoDoc.rtf in view mode; [Download] [Up]
Version 1.8.2 Copyright ©1995 by Information Technology Solutions, Inc. All Rights Reserved.
AutoDoc - Release 1.8.2
Guide for Use with Objective-C Source Code
Adam Swift, July 1995
Foreword
AutoDoc is a utility that generates NEXTSTEP-style Rich Text Formatted documentation for Objective-C objects by extracting comments imbedded in the object source code files. Autodoc will produce documentation for functions, definitions, macros, typedef's and global variables, however documenting these resources is not the primary goal of AutoDoc, and it expects to find their definitions and documentation within the framework of Objective-C objects.
AutoDoc was developed by Adam Swift <aswift@its.com> at Information Technology Solutions, and has been donated free of charge to the Public Domain. As author of AutoDoc, I would like to express my thanks to ITSolutions for allowing and encouraging me to make AutoDoc freely available to the public. It is important to see the chapter: Utterly Fun Legal & Warrantee Information before using AutoDoc.
Thanks also to Bill Bumgarner <bbum@friday.com>, Todd Anthony Nathan <todd@icebox.com>, and Kim Shrier <kim@media.com> for their bug fixes and improvements. Contributions, suggestions and questions regarding AutoDoc are very welcome, please send them either directly to Adam Swift or to the AutoDoc mailing list <autodoc@friday.com>. To subscribe to the mailing list, send a message with the subject, "subscribe", to <autodoc-request@friday.com>.
Table of Contents
1. Installing AutoDoc
2. Generating Documentation from Source Files
2.1 Generating Documentation for a Single Object
2.2 Generating Documentation for a Project's Objects
3. Writing Compliant Source Code and Comments
3.1 Copyright Info
3.2 Object Name
3.3 Inherits From
3.4 Category Name
3.5 Declared In
3.6 Class Description
3.7 Instance Variables
3.8 Method Types
3.9 Method Description
3.10 Functions
3.11 Macros
3.12 Symbolic Constants
3.13 Defined Types
3.14 Global Variables
4. Object Commenting Style and Philosophy
4.1 Text Formatting Switches for AutoDoc Style Comments
4.2 Text Formatting Guidelines
5. Invocation Options and Miscellaneous
6. Utterly Fun Legal & Warranty Information
1. Installing AutoDoc
This chapter describes how to install AutoDoc and tries to show you where to look if things go wrong. Note that there is an INSTALL file included in the release which gives a quick summary of the installation procedure.
The AutoDoc utility is actually a Perl script, in other words, you need to have access to the Perl program in order to use AutoDoc. If you do not already have Perl, it is generally available at: ftp.uu.net. AutoDoc was written to work with Perl version 5.001, but should work with version 5.000
AutoDoc must be able to access the perl program in order to execute the script. AutoDoc looks for the perl program in /usr/local/bin, if you cannot put perl there, you have to edit the first line of AutoDoc to refer to the actual location of perl. (e.g. If the Perl program is actually in /LocalDeveloper/Unix/bin, change the first line from: "#!/usr/local/perl" to: "#!/LocalDeveloper/Unix/bin/perl".)
AutoDoc must be able to access certain perl modules in order to run, the modules which were written specifically to support AutoDoc (and therefore are freely available) are available from the author <aswift@its.com>, and the common modules available at most perl resource ftp site. The complete list of required modules follows:
flush.pl - common
Getopt/Long.pm - common
Cwd.pm - common
Exporter.pm - common
AutodocSupport/FileSupport.pm
AutodocSupport/LogDebug.pm
AutodocSupport/ScanFile.pm
AutodocSupport/ParseComments.pm
AutodocSupport/GenerateRTF.pm
AutodocSupport/ReadSource.pm
AutodocSupport/DumpDocs.pm
The custom autodoc modules should be installed alongside to the perl5 modules on your filesystem (eg. /usr/local/lib/perl5/*). If you cannot copy the modules there, or if autodoc cannot locate the custom perl modules, you can instruct autodoc to find them in any directory you want. To do so, set the environment variable AD_PMLIBDIR to point to the directory which all of the .pm files are installed in:
For example, to include files from /Users/username/lib/perl5, add the following line to your .cshrc file:
setenv AD_PMLIBDIR '/Users/username/lib/perl5>'
AutoDoc is a command line utility, so the easiest way to run it is from a login shell. In the shell, change directories to the directory AutoDoc is in, and type "./autodoc" at the prompt to see if AutoDoc can run as it is configured on your computer. (You must set the executable flag on AutoDoc file permissions in order to run it by just typing "./autodoc") If everything works properly, AutoDoc should list its Invocation Options (See Invocation Options and Miscellaneous.)
If you get an error, or nothing happens, it is most likely a problem interacting with Perl. To see if it is working and accessible, try executing perl manually with the entire file path prepended, and the -v option to display the version.
2. Generating Documentation from Source Files
This chapter describes how to produce formatted documentation from source code files using AutoDoc. In order to generate NEXTSTEP style documentation for Objective-C objects with AutoDoc, you need to input the source code to AutoDoc. The following two sections describe common uses of AutoDoc.
2.1 Generating Documentation for a Single Object
The default operating mode of AutoDoc is to read each of the object names supplied on the command line, extract comments from the named objects source files (by scanning the files which have the same root name as the object name, with ".h" and ".m" appended) and produce Rich Text Formatted document files for each (by adding ".rtf" to the object's name). The files which AutoDoc produces by default are saved to the directory where the source files are located.
For example, suppose I have the source files MyObject.h and MyObject.m, and they are located in directory /Users/me/MyProject; I could generate documentation for them by typing the following into a shell:
% autodoc /Users/me/MyProject/MyObject
autodoc producing /Users/me/MyProject/MyObject.rtf ... done
%
And in the directory /Users/me/MyProject there should be a file named MyObject.rtf which contains the formatted documentation for MyObject. (Note, I must have write permissions for the /Users/me/MyProject directory for this to work.)
2.2 Generating Documentation for a Project's Objects
In order to produce documentation for a project directory full of object source files (plus recursively descending subdirectories of source code,) then to output all of the documentation in a separate destination directory, you need to supply a set of command line options to AutoDoc (See Invocation Options and Miscellaneous.)
For example, suppose I have a project filled with object source files and subprojects based in directory /Users/me/MyProject, and I want to produce the documentation files in ~/Docs/MyProject; I could generate documentation for them by typing the following into a shell:
% autodoc -tree -proj /Users/me/MyProject -dest ~/Docs/MyProject
autodoc creating ~/Docs/MyProject ... done
autodoc producing ~/Docs/MyProject/MyObject.rtf ... done
autodoc producing ~/Docs/MyProject/(other objects)
autodoc creating ~/Docs/MyProject/MySubproject ... done
autodoc producing ~/Docs/MyProject/MySubproject/MyOtherOb
ject.rtf ... done
...
%
And in the directory ~/Docs/MyProject there should be a file named MyObject.rtf which contains the formatted Documentation for MyObject. (Note, I must have write permissions for the directory ~/Docs/MyProject, or if it does not already exists, the directories which need to be created.)
3. Writing Compliant Source Code and Comments
This chapter outlines the information that you need to provide in your object's source code in order to produce documentation files which look like the NEXTSTEP developer documentation.
The information which is extracted from the source code files fits into two categories: elements from the actual definitions of the objects; and specially marked comments which are interpreted according to their location in the source. The comments which are used in producing the documentation must appear within /*" and "*/ comment delimiters. This style of comment is referred to as AutoDoc style comments. The one exception to this convention is copyright information, since it is automatically generated by DevMan, that information appears inside regular c style comment delimiters: /* and */.
In all of the examples given the object source code files used are the header file "MyObject.h" and the source file "MyObject.m". Also, when examples are shown with text in bold and italics, that text will be extracted by AutoDoc.
3.1 Copyright Info
The version number and year are extracted from the $Id: line inside regular (/* ... */) comments in the header file (the $Id: line is maintained by DevMan.app.) Note that the copyright owner may only be specified by using the command line flag -c.
Example: $Id: MyObject.h,v 1.1 1994/12/06 ...
Fail Case: If @interface is found before $Id:, the default is used.
Default: The version is not set, the year is set to the current year.
3.2 Object Name
Extracted from the object @interface declaration in the header file.
Example: @interface MyObject : SuperClass
Fail Case: If @interface is not found in the header file, the source is treated as a Resource Collection, not related to any specific object.
3.3 Inherits From
Extracted from the object @interface declaration in the header file. Optional AutoDoc style comments give further inheritance information.
Example: @interface MyObject : SuperClass /*" SuperSuperClass : ... :
RootClass "*/
Fail Case: If @interface is not found in the header file, the source is treated as a Resource Collection, not related to any specific object.
3.4 Category Name
Extracted from the object @interface declaration in the header file.
Example: @interface MyObject (CategoryName)
Fail Case: If @interface is not found in the header file, the source is treated as a Resource Collection, not related to any specific object.
3.5 Declared In
Extracted from the header file inclusion (#include or #import) in the source file.
Example: #import <filepath/MyObject.h> (Note, the <x> may also be "x")
Fail Case: If @implementation is found before the include/import, the default is used.
Default: The header file name with no file path, eg "MyObject.h"
3.6 Class Description
Extracted from AutoDoc style comments immediately following the object @implementation in the source file. Empty lines (two or more newlines) in the comment will generate separate paragraphs in the produced documentation.
Example: @implementation MyObject
/*" MyObject is .... "*/
Fail Case: If text other than the comment is found after the @implementation, the default is used.
Default: "No class description."
3.7 Instance Variables
Extracted from instance variable declarations in the header file. Optional AutoDoc style comments which follow a variable are associated with it.
Example: NXRect *myBounds; /*" The size and location of MyObject "*/
Fail Case: If methods follow the @interface before variables, this section in not included in the documentation.
3.8 Method Types
Extracted from method declarations in the header file. Optional AutoDoc style comments which precede methods define a method block label in the documentation.
Example: /*" Initializing a MyObject "*/
- init;
Fail Case: If @end is found before methods, this section in not included in the documentation.
3.9 Method Description
Class and instance method descriptions are extracted from AutoDoc style comments in method definitions in the source file. The comments must appear after the method name, but before the open bracket. Note that argument variables (a method's arguments) are automatically set in italicized text.
Example: - init
/*" Initializes and returns ... "*/
Fail Case: If the "{" is found before the method description, the default is used.
Default: "No method description."
3.10 Functions
Extracted from function declarations in the header file. Function's are only included in the documentation if they appear before the @interface line in the header file, and they must begin with the "extern" modifier. Documentation should appear before the function declaration and functions will be grouped by documentation.
Example: /*" Function documentation for foo() and bar() "*/
extern void foo();
extern int bar();
Fail Case: If @interface is found before functions, this section in not included in the documentation.
3.11 Macros
Extracted from macro definitions in the header file. Macro's are only included in the documentation if they appear before the @interface line in the header file. Documentation should appear before the macro definition and macros will be grouped by documentation.
Example: /*" Macro documentation for FOO() and BAR() "*/
#define FOO(x) whatever(x)
#define BAR(x) whateverelse(x)
Fail Case: If @interface is found before macro's, this section in not included in the documentation.
3.12 Symbolic Constants
Extracted from definitions in the header file. Constant's are only included in the documentation if they appear before the @interface line in the header file. Documentation should appear before the constant definition and constants will be grouped by documentation.
Example: /*" Constant documentation for BAZ "*/
#define BAZ 29
Fail Case: If @interface is found before constants, this section in not included in the documentation.
3.13 Defined Types
Extracted from definitions in the header file. Defined types are only included in the documentation if they appear before the @interface line in the header file. Documentation should appear before the typedef definition and defined types will be grouped by documentation.
Example: /*" Defined type documentation for FOOType "*/
typedef void FOOType;
Fail Case: If @interface is found before defined types, this section in not included in the documentation.
3.14 Global Variables
Extracted from declarations in the header file. Globals are only included in the documentation if they appear before the @interface line in the header file, and they must begin with an "extern" modifier. Documentation should appear before the global declaration and globals will be grouped by documentation.
Example: /*" Global variable documentation for RealGlobal "*/
extern int RealGlobal;
Fail Case: If @interface is found before global variables are defined, this section in not included in the documentation.
4. Object Commenting Style and Philosophy
This chapter describes the style and philosophy followed in the documentation of objects in the NEXTSTEP Developer Documentation. In order to produce documents of the same quality level, it is important that the text content be as consistent as the layout and formatting.
The best model to use for object design and documentation is the NEXTSTEP Developer Documentation.
4.1 Text Formatting Switches for AutoDoc Style Comments
AutoDoc provides switches which set the text appearing inside the documentation file into a special font style. These font style modifiers can be used inside any AutoDoc style comment.
#word and #{any text}
Used to set the word(s) into a bold type face. Note that the colons will not terminate the word in the example: #aMethod:withThree:arguments:.
%word and %{any text}
Used to set the word(s) into an italic type face.
_{item description...}
Used to set the item and the following words in the description onto a line by itself, seperated by a tab. Use this to create a line in a list of items and descriptions.
NOTE: In order to have % and # characters appear in the documentation as % and # characters, you should put the escape character \ immediately before them, as in: '\#' and '\%'.
4.2 Text Formatting Guidelines
All text formatting is automatically configured by AutoDoc, except for special style changes within the descriptions for the class, instance variables, methods, and method blocks. Each of these descriptions are placed inside AutoDoc style comments in the source code.
The only automatic formatting are: methods argument names will be automatically italicized within a method description, and the words self, id, super and nil will always be bolded.
WHEN TO USE BOLD TEXT
When methods are referred to in descriptions, they should appear in bold type, and the arguments and their types should not be included (e.g. renewRows:cols:.)
WHEN TO USE ITALIC TEXT
When you wish to emphasize an important concept, set it in italics (e.g. Each Window provides a field editor.) Italics should not be used for instance variables, and in general, instance variables should not be referenced directly in the documentation. Note that argument variables (a method's arguments) are automatically set in italicized text.
5. Invocation Options and Miscellaneous
This chapter describes the command-line switches (options) which may be used when executing AutoDoc. In addition to these command line switches, the AD_COPYRIGHT environment variable can be used to specify a default copyright owner. Command line switches can be used in full, or as single letters where unique (eg. -project can be specified as -p)
-project projectdirectory
Used to specify a project directory for reading in object source files. If no object source files are specified, then all files in projectdirectory (and its subdirectories) which form a pair, "FileName.h" and "FileName.m", as well as all files ending in ".h" (unless the -nosingles switch is specified,) are used to produce documentation. The documentation produced will be saved under the root name for each of the file pairs, and will be stored in the source files' directory (unless the -destination option is used.)
-destination destinationdirectory
Used to specify a destination directory for the documentation files produced. If the -tree option is also used, any source files which are prepended with a file path, will be placed in a subdirectory of the destination directory with the same file path.
-copyright copyrightowner
Used to specify an copyright owner for the copyright line on top of the documentation file. This will override the copyright owner specified by the environment variable AD_COPYRIGHT if both are used.
-version
Displays the version number and copyright information for AutoDoc.
-help
Displays the command line options available in AutoDoc, with synopses of their purpose.
-timestamp
Includes the current time and date in the copyright line of the documentation files created.
-nosingles
Excludes unpaired source files from the files used to produce documentation (i.e. if the file "FileName.h" is in a directory which does not contain "FileName.m", no documentation will be generated from it.)
-rtf
When combined with the -project and -destination options and no object files are specified, this will copy all files found with an 'rtf' or 'rtfd' extension found in the project directory or its subdirectories to the destination directory.
-force
Force autodoc to generate documentation files, even if the documentation files already exist and are newer than the source files. By defualt, autodoc will not overwrite documentation files which are newer than their source files.
-tree
Specifies that the documentation should be generated into a directory tree based on the directories traversed in locating the source files. This can be combined with the -project and -destination options to produce subprojects source file documentation in subdirectories of the destination directory.
-silent
Makes AutoDoc operate in silent mode, the only messages printed are error messages logged to stderr. Normally AutoDoc alerts the user whenever a file or directory is created.
-Debug level
Makes AutoDoc operate in DEBUG mode, verbose debugging messages are logged to stderr. The debugging levels for AutoDoc range fall in the the following categories:
1 Objects being processed and general AutoDoc configuration information
2 Object source files as they are accessed
3 Object data that is located, and a summary of what was found
4 Detailed information about all object data that is extracted
5 Complete logging of every line of text read in from the source files.
6. Utterly Fun Legal &Warranty Information
Because the AutoDoc is licensed free of charge, there is no warranty for the program. Copyright holder, Information Technology Solutions, is providing this program "as is" and this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.