[PATCH] dix: Improve documentation of the DIX private data functions.

[Aaron Plattner]

The functions exported by the devPrivates code were poorly documented.  I tried
to spruce it up a little.

Signed-off-by: Aaron Plattner <aplattner at nvidia.com>
---
A lot of people have been touching code that uses these recently, so I thought
it might be nice to document some of the nuances of the interface.

 include/privates.h |   64 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/include/privates.h b/include/privates.h
index 3c5c321..e6f788d 100644
--- a/include/privates.h
+++ b/include/privates.h
@@ -24,32 +24,71 @@ struct _Private;
 typedef struct _Private PrivateRec;
 
 /*
- * Request pre-allocated private space for your driver/module.
- * Calling this is not necessary if only a pointer by itself is needed.
+ * Request pre-allocated private space for your driver/module.  This function
+ * increases the amount of space allocated automatically when dixLookupPrivate
+ * is called on a PrivateRec that does not yet have a value associated with
+ * 'key'.
+ *
+ * This function will only increase the reserved size: if a size was previously
+ * requested, then dixRequestPrivate causes later calls to dixLookupPrivate to
+ * allocate the maximum of the old size and 'size'.  Requested sizes are reset
+ * to 0 by dixResetPrivates, which is called before each server generation.
+ *
+ * If dixRequestPrivate is not called with a nonzero size for 'key', then the
+ * module responsible for 'key' must manage the associated pointer itself with
+ * dixSetPrivate.
+ *
+ * dixRequestPrivate returns FALSE if it cannot store the requested size.
  */
 extern _X_EXPORT int
 dixRequestPrivate(const DevPrivateKey key, unsigned size);
 
 /*
- * Allocates a new private and attaches it to an existing object.
+ * Allocates space for an association of 'key' with a value in 'privates'.
+ *
+ * If a nonzero size was requested with dixRequestPrivate, then
+ * dixAllocatePrivate also allocates the requested amount of memory and
+ * associates the pointer to that memory with 'key' in 'privates'.  The
+ * allocated memory is initialized to zero.  This memory can only be freed by
+ * dixFreePrivates.
+ *
+ * If dixRequestPrivate was never called with a nonzero size, then
+ * dixAllocatePrivate associates NULL with 'key' in 'privates'.
+ *
+ * dixAllocatePrivate returns a pointer to the value associated with 'key' in
+ * 'privates', unless a memory allocation fails, in which case it returns NULL.
  */
 extern _X_EXPORT pointer *
 dixAllocatePrivate(PrivateRec **privates, const DevPrivateKey key);
 
 /*
  * Look up a private pointer.
+ *
+ * If no value is currently associated with 'key' in 'privates', then
+ * dixLookupPrivate calls dixAllocatePrivate and returns the resulting
+ * associated value.
+ *
+ * dixLookupPrivate returns NULL if a memory allocation fails.
  */
 extern _X_EXPORT pointer
 dixLookupPrivate(PrivateRec **privates, const DevPrivateKey key);
 
 /*
- * Look up the address of a private pointer.
+ * Look up the address of a private pointer.  If 'key' is not associated with a
+ * value in 'privates', then dixLookupPrivateAddr calls dixAllocatePrivate and
+ * returns a pointer to the resulting associated value.
+ *
+ * dixLookupPrivateAddr returns NULL if 'key' was not previously associated in
+ * 'privates' and a memory allocation fails.
  */
 extern _X_EXPORT pointer *
 dixLookupPrivateAddr(PrivateRec **privates, const DevPrivateKey key);
 
 /*
- * Set a private pointer.
+ * Associate 'val' with 'key' in 'privates' so that later calls to
+ * dixLookupPrivate(privates, key) will return 'val'.
+ *
+ * dixSetPrivate returns FALSE if a memory allocation fails.
  */
 extern _X_EXPORT int
 dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val);
@@ -63,22 +102,33 @@ typedef struct _PrivateCallback {
     pointer *value;	/* address of private pointer */
 } PrivateCallbackRec;
 
+/*
+ * Register a function to be called when dixAllocPrivate successfully associates
+ * 'key' with a new PrivateRec.
+ */
 extern _X_EXPORT int
 dixRegisterPrivateInitFunc(const DevPrivateKey key, 
 			   CallbackProcPtr callback, pointer userdata);
 
+/*
+ * Register a function to be called when dixFreePrivates unassociates 'key' with
+ * a PrivateRec.
+ */
 extern _X_EXPORT int
 dixRegisterPrivateDeleteFunc(const DevPrivateKey key,
 			     CallbackProcPtr callback, pointer userdata);
 
 /*
- * Frees private data.
+ * Unassociates all keys from 'privates', calls the callbacks registered with
+ * dixRegisterPrivateDeleteFunc, and frees all private data automatically
+ * allocated via dixRequestPrivate.
  */
 extern _X_EXPORT void
 dixFreePrivates(PrivateRec *privates);
 
 /*
- * Resets the subsystem, called from the main loop.
+ * Resets the privates subsystem.  dixResetPrivates is called from the main loop
+ * before each server generation.  This function must only be called by main().
  */
 extern _X_EXPORT int
 dixResetPrivates(void);
-- 
1.6.3.3