Change the format for APR function documentation. This uses the perldoc

scripts to generate either plain text, html, or any other format perldoc
can generate.  This also fixes the comments to say ap_pool instead of
ap_context.


git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@59869 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 96 insertions, 62 deletions

diff --git a/include/apr_lock.h b/include/apr_lock.h
index 2dfdd541a..b2ebc2382 100644
--- a/include/apr_lock.h
+++ b/include/apr_lock.h
@@ -69,89 +69,123 @@ typedef enum {APR_MUTEX, APR_READWRITE} ap_locktype_e;
 typedef struct ap_lock_t           ap_lock_t;
 
 /*   Function definitions */
-/* ***APRDOC********************************************************
- * ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type,
- *                            ap_lockscope_e scope, const char *fname, 
- *                            ap_context_t *cont)
- *    Create a new instance of a lock structure. 
- * arg 1) The newly created lock structure.
- * arg 2) The type of lock to create, one of:
- *            APR_MUTEX
- *            APR_READWRITE
- * arg 3) The scope of the lock to create, one of:
- *            APR_CROSS_PROCESS -- lock processes from the protected area.
- *            APR_INTRAPROCESS  -- lock threads from the protected area.
- *            APR_LOCKALL       -- lock processes and threads from the
- *                                 protected area.
- * arg 4) A file name to use if the lock mechanism requires one.  This
- *        argument should always be provided.  The lock code itself will
- *        determine if it should be used.
- * arg 5) The context to operate on.
- * NOTE:  APR_CROSS_PROCESS may lock both processes and threads, but it is
- *        only guaranteed to lock processes.
+/*
+
+=head1 ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type, ap_lockscope_e scope, const char *fname, ap_pool_t *cont)
+
+B<Create a new instance of a lock structure.>
+
+    arg 1) The newly created lock structure.
+    arg 2) The type of lock to create, one of:
+              APR_MUTEX
+              APR_READWRITE
+    arg 3) The scope of the lock to create, one of:
+              APR_CROSS_PROCESS -- lock processes from the protected area.
+              APR_INTRAPROCESS  -- lock threads from the protected area.
+              APR_LOCKALL       -- lock processes and threads from the
+                                   protected area.
+    arg 4) A file name to use if the lock mechanism requires one.  This
+          argument should always be provided.  The lock code itself will
+          determine if it should be used.
+    arg 5) The pool to operate on.
+
+B<NOTE>:  APR_CROSS_PROCESS may lock both processes and threads, but it is
+          only guaranteed to lock processes.
+
+=cut
  */
 ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type, 
                            ap_lockscope_e scope, const char *fname, 
                            ap_pool_t *cont);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_lock(ap_lock_t *lock)
- *    Lock a protected region. 
- * arg 1) The lock to set.
+/*
+
+=head1 ap_status_t ap_lock(ap_lock_t *lock)
+
+B<Lock a protected region.>
+
+    arg 1) The lock to set.
+
+=cut
  */
 ap_status_t ap_lock(ap_lock_t *lock);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_unlock(ap_lock_t *lock)
- *    Unlock a protected region. 
- * arg 1) The lock to reset.
+/*
+
+=head1 ap_status_t ap_unlock(ap_lock_t *lock)
+
+B<Unlock a protected region.>
+ 
+    arg 1) The lock to reset.
+
+=cut
  */
 ap_status_t ap_unlock(ap_lock_t *lock);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_destroy_lock(ap_lock_t *lock)
- *    Free the memory associated with a lock. 
- * arg 1) The lock to free.
- * NOTE:  If the lock is currently active when it is destroyed, it 
- *        will be unlocked first.
+/*
+
+=head1 ap_status_t ap_destroy_lock(ap_lock_t *lock)
+
+B<Free the memory associated with a lock.>
+ 
+    arg 1) The lock to free.
+
+B<NOTE>:  If the lock is currently active when it is destroyed, it 
+          will be unlocked first.
+
+=cut
  */
 ap_status_t ap_destroy_lock(ap_lock_t *lock);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, 
- *                                ap_context_t *cont)
- *    Re-open a lock in a child process. 
- * arg 1) The newly re-opened lock structure.
- * arg 2) A file name to use if the lock mechanism requires one.  This
- *        argument should always be provided.  The lock code itself will
- *        determine if it should be used.  This filename should be the same
- *        one that was passed to ap_create_lock
- * arg 3) The context to operate on.
- * NOTE:  This function doesn't always do something, it depends on the
- *        locking mechanism chosen for the platform, but it is a good
- *        idea to call it regardless, because it makes the code more
- *        portable. 
+/*
+
+=head1 ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, ap_pool_t *cont)
+
+B<Re-open a lock in a child process.>
+
+    arg 1) The newly re-opened lock structure.
+    arg 2) A file name to use if the lock mechanism requires one.  This
+           argument should always be provided.  The lock code itself will
+           determine if it should be used.  This filename should be the same
+           one that was passed to ap_create_lock
+    arg 3) The pool to operate on.
+
+B<NOTE>:  This function doesn't always do something, it depends on the
+           locking mechanism chosen for the platform, but it is a good
+           idea to call it regardless, because it makes the code more
+           portable. 
+
+=cut
  */
 ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, 
                                ap_pool_t *cont);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data)
- *    Return the context associated with the current lock.
- * arg 1) The currently open lock.
- * arg 2) The key to use when retreiving data associated with this lock
- * arg 3) The user data associated with the lock.
+/*
+
+=head1 ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data)
+
+B<Return the pool associated with the current lock.>
+
+    arg 1) The currently open lock.
+    arg 2) The key to use when retreiving data associated with this lock
+    arg 3) The user data associated with the lock.
+
+=cut
  */
 ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data);
 
-/* ***APRDOC********************************************************
- * ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key,
- *                              ap_status_t (*cleanup) (void *))
- *    Return the context associated with the current lock.
- * arg 1) The currently open lock.
- * arg 2) The user data to associate with the lock.
- * arg 3) The key to use when associating data with this lock
- * arg 4) The cleanup to use when the lock is destroyed.
+/*
+
+=head1 ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key, ap_status_t (*cleanup) (void *))
+
+B<Return the pool associated with the current lock.>
+
+    arg 1) The currently open lock.
+    arg 2) The user data to associate with the lock.
+    arg 3) The key to use when associating data with this lock
+    arg 4) The cleanup to use when the lock is destroyed.
+
+=cut
  */
 ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key,
                             ap_status_t (*cleanup) (void *));