From: Tom Keiser <tkeiser@sinenomine.net>
Date: Thu, 25 Mar 2010 17:08:51 +0000 (-0500)
Subject: Add some directory package doxygen comments
X-Git-Tag: openafs-devel-1_5_75~351
X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=6c53cd7ad3980bd38b4d522a55d439e99608eb11;p=packages%2Fo%2Fopenafs.git

Add some directory package doxygen comments

Change-Id: I75c358f08c71b2de722de03bb65fb8696657d57f
Reviewed-on: http://gerrit.openafs.org/1861
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>
---

diff --git a/src/dir/buffer.c b/src/dir/buffer.c
index 98277882e..e652accb6 100644
--- a/src/dir/buffer.c
+++ b/src/dir/buffer.c
@@ -97,6 +97,14 @@ DStat(int *abuffers, int *acalls, int *aios)
     return 0;
 }
 
+/**
+ * initialize the directory package.
+ *
+ * @param[in] abuffers  size of directory buffer cache
+ *
+ * @return operation status
+ *    @retval 0 success
+ */
 int
 DInit(int abuffers)
 {
@@ -131,6 +139,15 @@ DInit(int abuffers)
     return 0;
 }
 
+/**
+ * read a page out of a directory object.
+ *
+ * @param[in] fid   directory object fid
+ * @param[in] page  page in hash table to be read
+ *
+ * @return pointer to requested page in directory cache
+ *    @retval NULL read failed
+ */
 void *
 DRead(register afs_int32 *fid, register int page)
 {
diff --git a/src/dir/salvage.c b/src/dir/salvage.c
index ac85ae0f0..02830862c 100644
--- a/src/dir/salvage.c
+++ b/src/dir/salvage.c
@@ -72,8 +72,14 @@ ComputeUsedPages(register struct DirHeader *dhp)
     return usedPages;
 }
 
-/* returns true if something went wrong checking, or if dir is fine.  Returns
- * false if we *know* that the dir is bad.
+/**
+ * check whether a directory object is ok.
+ *
+ * @param[in] file  opaque pointer to directory object fid
+ *
+ * @return operation status
+ *    @retval 1 dir is fine, or something went wrong checking
+ *    @retval 0 we *know* that the dir is bad
  */
 int
 DirOK(void *file)
@@ -420,13 +426,18 @@ DirOK(void *file)
     return 1;
 }
 
-/* This routine is called with six parameters.  The first is the id of 
- * the original, currently suspect, directory.  The second is the file 
- * id of the place the salvager should place the new, fixed, directory. 
- * The third and the fourth parameters are the vnode number and the
- * uniquifier of the currently suspect directory. The fifth and the
- * sixth parameters are the vnode number and the uniquifier of the
- * parent directory.
+/**
+ * Salvage a directory object.
+ *
+ * @param[in] fromFile  fid of original, currently suspect directory object
+ * @param[in] toFile    fid where salvager will place new, fixed directory
+ * @param[in] vn        vnode of currently suspect directory
+ * @param[in] vu        uniquifier of currently suspect directory
+ * @param[in] pvn       vnode of parent directory
+ * @param[in] pvu       uniquifier of parent directory
+ *
+ * @return operation status
+ *    @retval 0 success
  */
 int
 DirSalvage(void *fromFile, void *toFile, afs_int32 vn, afs_int32 vu,