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/03/28 01:02:12 UTC
cvs commit: apache-2.0/src/lib/apr APRDesign
rbb 00/03/27 15:02:12
Modified: src/lib/apr APRDesign
Log:
Added a section on documenting APR functions.
Revision Changes Path
1.5 +23 -0 apache-2.0/src/lib/apr/APRDesign
Index: APRDesign
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/APRDesign,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- APRDesign 1999/11/11 15:10:05 1.4
+++ APRDesign 2000/03/27 23:02:11 1.5
@@ -157,3 +157,26 @@
2) If a function needs a context, it should be the last argument.
3) These rules are flexible, especially if it makes the code easier
to understand because it mimics a standard function.
+
+Documentation
+
+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 format for the comment block is:
+
+/* ***APRDOC********************************************************
+ * Function prototype with variable names
+ * A one or two line description of what the function does.
+ * arg 1) A brief description of the first argument.
+ * ...
+ * arg N) A brief description of the Nth argument.
+ * NOTE: This is optional. If there is anything programmers need to
+ * know about your function, add it here.
+ */
+
+For an actual example, look at any function in the fileio/unix directory.