From 6c53cd7ad3980bd38b4d522a55d439e99608eb11 Mon Sep 17 00:00:00 2001
From: Tom Keiser <tkeiser@sinenomine.net>
Date: Thu, 25 Mar 2010 12:08:51 -0500
Subject: [PATCH] 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>
---
 src/dir/buffer.c  | 17 +++++++++++++++++
 src/dir/salvage.c | 29 ++++++++++++++++++++---------
 2 files changed, 37 insertions(+), 9 deletions(-)

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,
-- 
2.39.5