home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-2.iso / Unix / developer / docgen.0.3.2.README < prev    next >
Encoding:
Text File  |  1996-03-07  |  8.3 KB  |  221 lines
  1.  
  2. Docgen v0.3.2
  3. ******
  4.  
  5.     docgen is a program to automatically create documentation of
  6.     Objective C source code.
  7.  
  8.     You can create documentation in multiple formats including 
  9.     RTF, HTML and plain text.
  10.     
  11.     You can run docgen with a starting directory, and docgen will then
  12.     look for any matching .h and .m class files. From those files it will
  13.     create NeXT-style documents.
  14.  
  15. NEW The '-R' recursive option is seven times faster.
  16.     Docgen should be easier to compile on non-NextStep systems.
  17.  
  18. Requirements
  19. ************
  20.  
  21.     To produce .rtf documentation, docgen requires just a standard 
  22.         C compiler.
  23.     To do .txt and .html you need Objective C with either the NeXT 
  24.         or GNU runtime. 
  25.     To dynamically load formatting classes requires the NeXT runtime.
  26.  
  27. Availability
  28. ************
  29.  
  30.         ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.2.tar.gz
  31.  
  32.         ftp://next-ftp.peak.org/software/NeXT/sources/util/docgen-0.3.2.tar.gz
  33.  
  34.     Quad-Fat Installer package for NextStep:
  35.  
  36.         ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.2.pkg.tar
  37.  
  38.     Example output can be seen at:
  39.  
  40.         http://www.csis.gvsu.edu/~berezaw/programming.html
  41.  
  42.     A patch file to go from 0.3.1 to 0.3.2 is available at:
  43.     
  44.         ftp://ftp.csis.gvsu.edu/pub/docgen/docgen-0.3.0-to-0.3.1.diff.gz
  45.  
  46. Changes since 0.3.1
  47. *******
  48.  
  49.     * 0.3.2 the '-R' recursive option is now 700% faster
  50.  
  51.         changed the behavior of the '-e' option. Text given in the '-e'
  52.             is added to the class implementation file name
  53.                     
  54.         expanded '-C' switch to parse comments on lines with "/*"
  55.             and on lines with "*/"
  56.                 
  57.         assorted big-fixes/suggestions/code-handling
  58.             (Alex Blakemore, Pieter Schoenmakers, Michal Brouwer,
  59.              Ralf E. Stranzenbach, Georg Tuparev)
  60.  
  61.  
  62.     * 0.3.1 expanded '-R' switch to have docgen search below 
  63.                 the '-d' directory for .h files that match
  64.                 with .m files
  65.                 (the way -R worked before was not a bug but
  66.                     a feature) 
  67.  
  68.             added '-a' and '-b' switch to have docgen parse
  69.                 comments before and/or after method names
  70.  
  71. ToDo
  72. ****
  73.  
  74.     * Enhance the HTML format output
  75.  
  76.     See the TODO file from the distribution.
  77.  
  78. Usage
  79. *****
  80.  
  81.     'docgen -?' or docgen with any unknown option will give you
  82.     the usage template.
  83.  
  84.     Usage:  docgen
  85.             [-d dir] [-l library] [-I headerdirs] [-R]
  86.             [-v #] [-s string] [-e string] [-f class] [-B directory] 
  87.             [-x] [-S] [-F] [-C] [-A] [-D] [-a] [-b]
  88.  
  89.     [-d dir]                Root dir to begin search for files
  90.     [-l library]            dir to dump RTF files into
  91.     [-I headerdirs]         List of directories separated by ':'
  92.     [-R]                    recursively search the header dirs
  93.     [-s string]             Separator for inheritance path output
  94.     [-v (0-5)]              level of verbosity(0 = none, 5 = all)
  95.     [-e string]             Name of directory to put in Declared In:
  96.     [-f classname]          The name of the Formatting class to use
  97.     [-B ModuleDir]          The name of a directory containing modules
  98.     [-x]                    Don't document methods that begin with _
  99.     [-F]                    Don't check for net-like fancy text.
  100.     [-S]                    Sort the methods in the descriptions.
  101.     [-C]                    Print the first line of comments.
  102.     [-A]                    Auto-document ALL set and get methods.
  103.     [-D]                    Show default values for all the above.
  104.     [-a]                    Parse comments after method name in 
  105.                             implementation. (default)
  106.     [-b]                    Parse comments before the method name 
  107.                             (may be used with -a)"
  108.  
  109.  
  110.     -d  docgen will begin searching from the '-d' directory looking
  111.         for '*.m' and '*.h' files.
  112.  
  113.     -l  When it finds matching '.h' and '.m' files, docgen
  114.         parses through them creating useful documentation files in the
  115.         directory specified by '-l'
  116.  
  117.     -I  While parsing through the files, docgen will try to trace the
  118.         inheritance of objects all the way back to 'Object' if possible. The
  119.         '-I' option is a list of directories seperated by ':' that docgen will
  120.         search in for '.h' files while tracing inheritance. The directories
  121.         given with '-I' are searched _in addition to_ the default search
  122.         paths.
  123.  
  124.     -R  The '-R' switch control whether or not docgen will search below the
  125.         directories given as the '.h' search path.
  126.  
  127.     -s  The '-s' option is a string that docgen will use to seperate the list
  128.         of objects in the traced inheritance output.
  129.  
  130.     -v  The '-v' option controls the amount of stderr output. All output from
  131.         docgen goes either to the '.rtf' file it's creating or to 'stderr'
  132.  
  133.         '-v 0' will cause docgen to never output anything. Anything above
  134.         '-v3' will be pretty useless.
  135.  
  136.     -e  The '-e' options lets you specify a string that will go in the
  137.         Declared In: header of the .rtf file. It can be anything, because
  138.         right now nothing else is added to your string. If you don't
  139.         specifiy the '-e' option, then the full path of the directory
  140.         will go there.
  141.  
  142.     -f  The '-f' option lets you choose a Formatter class to use for
  143.         the output format. The name you use is the actual name of the class.
  144.         These are the built-in classes:
  145.  
  146.             class               usage
  147.  
  148.             RTFFormatter        -f RTF
  149.             HTMLFormatter       -f HTML
  150.             TXTFormatter        -f TXT
  151.  
  152.         You can abbrieviate the names by leaving of the 'Formatter'.
  153.  
  154.         *In future version of docgen, you will be able to dynamically
  155.         load classes which aren't built-in at compile time.
  156.  
  157.         Currently you can only do one format at a time.
  158.  
  159.                If docgen can not find the class from the -f
  160.           option, it will try to load a module for the class. By
  161.           default docgen will search this path list (.
  162.           /usr/local/lib/docgen /usr/lib/docgen) for object files
  163.           to load. If ClassName is the class in the -f option,
  164.           docgen will try to load "path/ClassName",
  165.           "path/ClassName.o", "path/ClassNameFormatter" and
  166.           "path/ClassNameFormatter.o" for each path in the search
  167.           list.
  168.  
  169.           You can specify a specific object file to load with the
  170.           -B option.
  171.  
  172.      -B : This specifies the full pathname of a directory to look
  173.           in for the Formatter class module specified in the -f
  174.           option. This allows new output formats to be dynami-
  175.           cally added to docgen. If the -B option is specifed,
  176.           then docgen will look there first for modules.
  177.           The -B option is only used with the -f option.
  178.  
  179.     -x  Using '-x' will cause docgen to skip over any method whose
  180.         name begins with '_'.
  181.  
  182.     -S  The '-S' option will cause docgen to sort the method names in
  183.         the description section. In the Method Types section, the names
  184.         are left as listed in the .h file. It will sort the Clss Methods
  185.         seperately from the Instance Methods.
  186.  
  187.     -F  The '-F' option will turn off fancy text search. Fancy text
  188.         is done one word at a time.
  189.  
  190.     -C  The '-C' option will cause docgen to print comment text that is the
  191.         same line as the "/*" comment starter. This is by default off. 
  192.  
  193.     -A  The '-A' option will cause docgen to automatically document all set
  194.         and get type methods. Normally docgen will only auto-doc one-line
  195.         methods.
  196.  
  197.     -D  With the '-D' option docgen will print a list of default argument
  198.         values, and some other internal values set during compilation.'
  199.     -a  If the -a option is used then docgen will include comments that
  200.         come between the method name and the first '{' in the implementation.
  201.         It can be used with the -b option.
  202.  
  203.     -b  If the -b option is used then docgen will include comments that
  204.         come before the method name in the implementation.
  205.         It can be used with the -b option.
  206.  
  207. Code Format
  208. ***********
  209.  
  210. Look at aClass.m and aClass.h for an example of the stuff docgen
  211. can do.
  212.  
  213. Thanks
  214. ******
  215.  
  216. Thanks go to Dr. Carl Erickson for "suggesting" the program, and
  217. Jim Wissner and Carl for beta-testing and giving ideas for additions.
  218.  
  219. Alex Blakemore, Pieter Schoenmakers, Michal Brouwer,
  220. Ralf E. Stranzenbach, and Georg Tuparev for suggestions/fixes.
  221.