You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@locus.apache.org on 2000/07/28 22:21:17 UTC

cvs commit: apache-2.0/src/lib/apr APRDesign

rbb         00/07/28 13:21:15

  Modified:    src/lib/apr APRDesign
  Log:
  Update the APR docs about how to document APR functions.
  
  Revision  Changes    Path
  1.14      +17 -21    apache-2.0/src/lib/apr/APRDesign
  
  Index: APRDesign
  ===================================================================
  RCS file: /home/cvs/apache-2.0/src/lib/apr/APRDesign,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- APRDesign	2000/06/10 00:44:46	1.13
  +++ APRDesign	2000/07/28 20:21:13	1.14
  @@ -161,33 +161,29 @@
   
   Whenever a new function is added to APR, it MUST be documented.  New 
   functions will not be committed unless there are docs to go along with them.
  -The documentation should be a comment block above the function in the unix
  -.c file.  This does not mean you must implement the function for Unix.  But,
  -it would be nice if you submitted a file with the prototypes and the comments
  -above the prototypes to be checked into the unix tree.
  +The documentation should be a comment block above the function in the header
  +file.
   
   The format for the comment block is:
   
  -/*
  -
  -=head1 function prototype
  -
  -B<Brief description of function>
  -
  -    arg 1)  explanation of arg 1
  -    arg 2)  explanation of arg 2
  -    arg N)  explanation of arg N
  -
  -B<NOTE>:  Any extra information the programmer needs.
  -
  -=cut
  +/**
  + * Brief description of the function
  + * @param parma_1_name explanation
  + * @param parma_2_name explanation
  + * @param parma_n_name explanation
  + * @tip Any extra information people should know.
  + * @deffunc function prototype if required
    */                                                                             
   
  -The spacing for the documentation is VERY important, because the docs are
  -processed with perldoc, and this spacing is required for the perldoc scripts
  -to work properly.
  +The last line is not strictly needed.  The parser in ScanDoc is not perfect
  +yet, and it can not parse prototypes that are in any form other than
  +	return_type program_name(type1 param1, type2 param2, ...)
  +This means that any function prototype that resembles:
  +	APR_EXPORT(ap_status_t) ap_foo(int f1, char *f2)
  +will need the deffunc.
   
  -For an actual example, look at any function in the fileio/unix directory.
  +For an actual example, look at any file in the include directory (ap_tables.h
  +hasn't been done yet).
   
   APR Error reporting