cvs commit: httpd-docs-2.0/htdocs/manual/developer documenting

[rb...@locus.apache.org]

rbb         00/07/29 07:30:29

  Added:       htdocs/manual/developer documenting
  Log:
  Add a small doc on how to document the APIs for use with ScanDoc.
  
  Revision  Changes    Path
  1.1                  httpd-docs-2.0/htdocs/manual/developer/documenting
  
  Index: documenting
  ===================================================================
  Apache 2.0 is using ScanDoc to document the API's and global variables in 
  the code.  This will explain the basics of how to document using Scandoc.
  
  To start a scandoc block, use /**
  To end a scandoc block, use */
  
  In the middle of the block, there are multiple tags we can use:
  
   Description of this functions purpose
   @param parameter_name description
   @tip Any information the programmer should know
   @deffunc function prototype.
  
  The deffunc is not always necessary.  ScanDoc does not have a full parser in
  it, so any prototype that use a macro in the return type declaration is too
  complex for scandoc.  Those functions require a deffunc.
  
  An example:
  
  /**
   * return the final element of the pathname
   * @param pathname The path to get the final element of
   * @return the final element of the path
   * @tip Examples:
   * <PRE>
   *                 "/foo/bar/gum"   -> "gum"
   *                 "/foo/bar/gum/"  -> ""
   *                 "gum"            -> "gum"
   *                 "wi\\n32\\stuff" -> "stuff"
   * </PRE>
   * @deffunc const char * ap_filename_of_pathname(const char *pathname)
   */
  
  At the top of the header file, we always include
  
  /**
   * @package Name of library header
   */
  
  ScanDoc uses a new html file for each package.  The html files are named:
  
  Name of library header.html, so try to be concise with your names