Add some directory package doxygen comments
authorTom Keiser <tkeiser@sinenomine.net>
Thu, 25 Mar 2010 17:08:51 +0000 (12:08 -0500)
committerDerrick Brashear <shadow@dementia.org>
Tue, 27 Apr 2010 21:37:09 +0000 (14:37 -0700)
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
src/dir/salvage.c

index 9827788..e652acc 100644 (file)
@@ -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)
 {
index ac85ae0..0283086 100644 (file)
@@ -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,