libfrog/xfs_scrub: improve iteration function documentation

Between libfrog and xfs_scrub, we have several item collection iteration
functions that take a pointer to a function that will be called for
every item in that collection.  They're not well documented, so improve
the description of when they'll be called and what kinds of return
values they expect.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
Signed-off-by: Eric Sandeen <sandeen@sandeen.net>

5 files changed, 30 insertions, 2 deletions

diff --git a/libfrog/ptvar.h b/libfrog/ptvar.h
index 42865c0b2f..b7d02d6269 100644
--- a/libfrog/ptvar.h
+++ b/libfrog/ptvar.h
@@ -8,11 +8,15 @@
 
 struct ptvar;
 
-typedef int (*ptvar_iter_fn)(struct ptvar *ptv, void *data, void *foreach_arg);
-
 int ptvar_alloc(size_t nr, size_t size, struct ptvar **pptv);
 void ptvar_free(struct ptvar *ptv);
 void *ptvar_get(struct ptvar *ptv, int *ret);
+
+/*
+ * Visit each per-thread value.  Return 0 to continue iteration or nonzero to
+ * stop iterating and return to the caller.
+ */
+typedef int (*ptvar_iter_fn)(struct ptvar *ptv, void *data, void *foreach_arg);
 int ptvar_foreach(struct ptvar *ptv, ptvar_iter_fn fn, void *foreach_arg);
 
 #endif /* __LIBFROG_PTVAR_H__ */
diff --git a/scrub/filemap.h b/scrub/filemap.h
index cb33172982..219be57511 100644
--- a/scrub/filemap.h
+++ b/scrub/filemap.h
@@ -14,6 +14,10 @@ struct xfs_bmap {
 	uint32_t	bm_flags;	/* output flags */
 };
 
+/*
+ * Visit each inode fork mapping.  Return true to continue iteration or false
+ * to stop iterating and return to the caller.
+ */
 typedef bool (*xfs_bmap_iter_fn)(struct scrub_ctx *ctx, const char *descr,
 		int fd, int whichfork, struct fsxattr *fsx,
 		struct xfs_bmap *bmap, void *arg);
diff --git a/scrub/inodes.h b/scrub/inodes.h
index 3341c6d9ed..e58795e7f4 100644
--- a/scrub/inodes.h
+++ b/scrub/inodes.h
@@ -6,6 +6,12 @@
 #ifndef XFS_SCRUB_INODES_H_
 #define XFS_SCRUB_INODES_H_
 
+/*
+ * Visit each space mapping of an inode fork.  Return 0 to continue iteration
+ * or a positive error code to interrupt iteraton.  If ESTALE is returned,
+ * iteration will be restarted from the beginning of the inode allocation
+ * group.  Any other non zero value will stop iteration.
+ */
 typedef int (*xfs_inode_iter_fn)(struct scrub_ctx *ctx,
 		struct xfs_handle *handle, struct xfs_bulkstat *bs, void *arg);
 
diff --git a/scrub/spacemap.h b/scrub/spacemap.h
index 8f2f0a01bd..c29c43a51c 100644
--- a/scrub/spacemap.h
+++ b/scrub/spacemap.h
@@ -6,6 +6,10 @@
 #ifndef XFS_SCRUB_SPACEMAP_H_
 #define XFS_SCRUB_SPACEMAP_H_
 
+/*
+ * Visit each space mapping in the filesystem.  Return true to continue
+ * iteration or false to stop iterating and return to the caller.
+ */
 typedef bool (*xfs_fsmap_iter_fn)(struct scrub_ctx *ctx, const char *descr,
 		struct fsmap *fsr, void *arg);
 
diff --git a/scrub/vfs.h b/scrub/vfs.h
index caef8969b0..af23674a7f 100644
--- a/scrub/vfs.h
+++ b/scrub/vfs.h
@@ -6,8 +6,18 @@
 #ifndef XFS_SCRUB_VFS_H_
 #define XFS_SCRUB_VFS_H_
 
+/*
+ * Visit a subdirectory prior to iterating entries in that subdirectory.
+ * Return true to continue iteration or false to stop iterating and return to
+ * the caller.
+ */
 typedef bool (*scan_fs_tree_dir_fn)(struct scrub_ctx *, const char *,
 		int, void *);
+
+/*
+ * Visit each directory entry in a directory.  Return true to continue
+ * iteration or false to stop iterating and return to the caller.
+ */
 typedef bool (*scan_fs_tree_dirent_fn)(struct scrub_ctx *, const char *,
 		int, struct dirent *, struct stat *, void *);