This is the README for docgen.0.3.2.s.tar.gz [Download] [Browse] [Up]
Docgen v0.3.2
******
docgen is a program to automatically create documentation of
Objective C source code.
You can create documentation in multiple formats including
RTF, HTML and plain text.
You can run docgen with a starting directory, and docgen will then
look for any matching .h and .m class files. From those files it will
create NeXT-style documents.
NEW The '-R' recursive option is seven times faster.
Docgen should be easier to compile on non-NextStep systems.
Requirements
************
To produce .rtf documentation, docgen requires just a standard
C compiler.
To do .txt and .html you need Objective C with either the NeXT
or GNU runtime.
To dynamically load formatting classes requires the NeXT runtime.
Availability
************
ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.2.tar.gz
ftp://next-ftp.peak.org/software/NeXT/sources/util/docgen-0.3.2.tar.gz
Quad-Fat Installer package for NextStep:
ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.2.pkg.tar
Example output can be seen at:
http://www.csis.gvsu.edu/~berezaw/programming.html
A patch file to go from 0.3.1 to 0.3.2 is available at:
ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.0-to-0.3.1.diff.gz
Changes since 0.3.1
*******
* 0.3.2 the '-R' recursive option is now 700% faster
changed the behavior of the '-e' option. Text given in the '-e'
is added to the class implementation file name
expanded '-C' switch to parse comments on lines with "/*"
and on lines with "*/"
assorted big-fixes/suggestions/code-handling
(Alex Blakemore, Pieter Schoenmakers, Michal Brouwer,
Ralf E. Stranzenbach, Georg Tuparev)
* 0.3.1 expanded '-R' switch to have docgen search below
the '-d' directory for .h files that match
with .m files
(the way -R worked before was not a bug but
a feature)
added '-a' and '-b' switch to have docgen parse
comments before and/or after method names
ToDo
****
* Enhance the HTML format output
See the TODO file from the distribution.
Usage
*****
'docgen -?' or docgen with any unknown option will give you
the usage template.
Usage: docgen
[-d dir] [-l library] [-I headerdirs] [-R]
[-v #] [-s string] [-e string] [-f class] [-B directory]
[-x] [-S] [-F] [-C] [-A] [-D] [-a] [-b]
[-d dir] Root dir to begin search for files
[-l library] dir to dump RTF files into
[-I headerdirs] List of directories separated by ':'
[-R] recursively search the header dirs
[-s string] Separator for inheritance path output
[-v (0-5)] level of verbosity(0 = none, 5 = all)
[-e string] Name of directory to put in Declared In:
[-f classname] The name of the Formatting class to use
[-B ModuleDir] The name of a directory containing modules
[-x] Don't document methods that begin with _
[-F] Don't check for net-like fancy text.
[-S] Sort the methods in the descriptions.
[-C] Print the first line of comments.
[-A] Auto-document ALL set and get methods.
[-D] Show default values for all the above.
[-a] Parse comments after method name in
implementation. (default)
[-b] Parse comments before the method name
(may be used with -a)"
-d docgen will begin searching from the '-d' directory looking
for '*.m' and '*.h' files.
-l When it finds matching '.h' and '.m' files, docgen
parses through them creating useful documentation files in the
directory specified by '-l'
-I While parsing through the files, docgen will try to trace the
inheritance of objects all the way back to 'Object' if possible. The
'-I' option is a list of directories seperated by ':' that docgen will
search in for '.h' files while tracing inheritance. The directories
given with '-I' are searched _in addition to_ the default search
paths.
-R The '-R' switch control whether or not docgen will search below the
directories given as the '.h' search path.
-s The '-s' option is a string that docgen will use to seperate the list
of objects in the traced inheritance output.
-v The '-v' option controls the amount of stderr output. All output from
docgen goes either to the '.rtf' file it's creating or to 'stderr'
'-v 0' will cause docgen to never output anything. Anything above
'-v3' will be pretty useless.
-e The '-e' options lets you specify a string that will go in the
Declared In: header of the .rtf file. It can be anything, because
right now nothing else is added to your string. If you don't
specifiy the '-e' option, then the full path of the directory
will go there.
-f The '-f' option lets you choose a Formatter class to use for
the output format. The name you use is the actual name of the class.
These are the built-in classes:
class usage
RTFFormatter -f RTF
HTMLFormatter -f HTML
TXTFormatter -f TXT
You can abbrieviate the names by leaving of the 'Formatter'.
*In future version of docgen, you will be able to dynamically
load classes which aren't built-in at compile time.
Currently you can only do one format at a time.
If docgen can not find the class from the -f
option, it will try to load a module for the class. By
default docgen will search this path list (.
/usr/local/lib/docgen /usr/lib/docgen) for object files
to load. If ClassName is the class in the -f option,
docgen will try to load "path/ClassName",
"path/ClassName.o", "path/ClassNameFormatter" and
"path/ClassNameFormatter.o" for each path in the search
list.
You can specify a specific object file to load with the
-B option.
-B : This specifies the full pathname of a directory to look
in for the Formatter class module specified in the -f
option. This allows new output formats to be dynami-
cally added to docgen. If the -B option is specifed,
then docgen will look there first for modules.
The -B option is only used with the -f option.
-x Using '-x' will cause docgen to skip over any method whose
name begins with '_'.
-S The '-S' option will cause docgen to sort the method names in
the description section. In the Method Types section, the names
are left as listed in the .h file. It will sort the Clss Methods
seperately from the Instance Methods.
-F The '-F' option will turn off fancy text search. Fancy text
is done one word at a time.
-C The '-C' option will cause docgen to print comment text that is the
same line as the "/*" comment starter. This is by default off.
-A The '-A' option will cause docgen to automatically document all set
and get type methods. Normally docgen will only auto-doc one-line
methods.
-D With the '-D' option docgen will print a list of default argument
values, and some other internal values set during compilation.'
-a If the -a option is used then docgen will include comments that
come between the method name and the first '{' in the implementation.
It can be used with the -b option.
-b If the -b option is used then docgen will include comments that
come before the method name in the implementation.
It can be used with the -b option.
Code Format
***********
Look at aClass.m and aClass.h for an example of the stuff docgen
can do.
Thanks
******
Thanks go to Dr. Carl Erickson for "suggesting" the program, and
Jim Wissner and Carl for beta-testing and giving ideas for additions.
Alex Blakemore, Pieter Schoenmakers, Michal Brouwer,
Ralf E. Stranzenbach, and Georg Tuparev for suggestions/fixes.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.