LU-9633 fid: Add kernel doc style for fid/*.c

This patch converts existing functional comments
to kernel doc style comments and removes '/**' for
comments which is not meant to be a kernel-doc comment

Test-Parameters: trivial
Signed-off-by: Arshad Hussain <arshad.hussain@aeoncomputing.com>
Change-Id: I1e844495cc9bffba8b6ec065577470075523dccc
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58419
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Petros Koutoupis <petros.koutoupis@hpe.com>
Reviewed-by: James Simmons <jsimmons@infradead.org>
Reviewed-by: Anjus George <georgea@ornl.gov>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/fid/fid_handler.c b/lustre/fid/fid_handler.c
index ef66819..d831465 100644 (file)
--- a/lustre/fid/fid_handler.c
+++ b/lustre/fid/fid_handler.c
@@ -77,12 +77,21 @@ static inline void range_alloc(struct lu_seq_range *to,
 }
 
 /**
+ * __seq_server_alloc_super() - allocate new super sequence
+ * @seq: server sequence from which the super sequence will be derived
+ * @out: (Output Param) store the returned super seq range
+ * @env: execution environment
+ *
  * On controller node, allocate new super sequence for regular sequence server.
  * As this super sequence controller, this node suppose to maintain fld
- * and update index.
- * \a out range always has currect mds node number of requester.
+ * and update index. @out range always has correct mds node number of requester
+ * (Super sequence is pool of sequence number. Server sequence is a subset of
+ *  sequence number allocated from super sequence pool)
+ *
+ * Return:
+ * * %0: Success
+ * * %negative: Failure
  */
-
 static int __seq_server_alloc_super(struct lu_server_seq *seq,
                                    struct lu_seq_range *out,
                                    const struct lu_env *env)
@@ -233,17 +242,17 @@ static int range_alloc_set(const struct lu_env *env,
 }
 
 /**
- * Check if the sequence server has sequence avaible
+ * seq_server_check_and_alloc_super() - Check if the sequence server has
+ * sequence available
+ * @env: execution environment
+ * @seq: server sequence
  *
- * Check if the sequence server has sequence avaible, if not, then
+ * Check if the sequence server has sequence available, if not, then
  * allocating super sequence from sequence manager (MDT0).
  *
- * \param[in] env      execution environment
- * \param[in] seq      server sequence
- *
- * \retval             negative errno if allocating new sequence fails
- * \retval             0 if there is enough sequence or allocating
- *                      new sequence succeeds
+ * Return:
+ * * %0: if there is enough sequence or allocating new sequence succeeds
+ * * %-ERRNO: if allocating new sequence fails
  */
 int seq_server_check_and_alloc_super(const struct lu_env *env,
                                     struct lu_server_seq *seq)

diff --git a/lustre/fid/fid_lib.c b/lustre/fid/fid_lib.c
index 96d4e54..01790ad 100644 (file)
--- a/lustre/fid/fid_lib.c
+++ b/lustre/fid/fid_lib.c
@@ -27,7 +27,7 @@
 
 #include "fid_internal.h"
 
-/**
+/*
  * A cluster-wide range from which fid-sequences are granted to servers and
  * then clients.
  *

diff --git a/lustre/fid/fid_request.c b/lustre/fid/fid_request.c
index 5afb805..f10f937 100644 (file)
--- a/lustre/fid/fid_request.c
+++ b/lustre/fid/fid_request.c
@@ -231,14 +231,14 @@ static int seq_client_alloc_seq(const struct lu_env *env,
 }
 
 /**
- * Allocate the whole non-used seq to the caller.
+ * seq_client_get_seq() - Allocate the whole non-used seq to the caller
+ * @env: pointer to the thread context
+ * @seq: pointer to the client sequence manager
+ * @seqnr: to hold the new allocated sequence
  *
- * \param[in] env      pointer to the thread context
- * \param[in,out] seq  pointer to the client sequence manager
- * \param[out] seqnr   to hold the new allocated sequence
- *
- * \retval             0 for new sequence allocated.
- * \retval             Negative error number on failure.
+ * Return:
+ * * %0: Success (for new sequence allocated)
+ * * %-ERRNO: On Failure
  */
 int seq_client_get_seq(const struct lu_env *env,
                       struct lu_client_seq *seq, u64 *seqnr)
@@ -275,16 +275,17 @@ int seq_client_get_seq(const struct lu_env *env,
 EXPORT_SYMBOL(seq_client_get_seq);
 
 /**
- * Allocate new fid on passed client @seq and save it to @fid.
- *
- * \param[in] env      pointer to the thread context
- * \param[in,out] seq  pointer to the client sequence manager
- * \param[out] fid     to hold the new allocated fid
+ * seq_client_alloc_fid() - Allocate new FID on passed client @seq and save
+ * it to @fid.
+ * @env: pointer to the thread context
+ * @seq: pointer to the client sequence manager
+ * @fid: to hold the new allocated FID
  *
- * \retval             1 for notify the caller that sequence switch
- *                     is performed to allow it to setup FLD for it.
- * \retval             0 for new FID allocated in current sequence.
- * \retval             Negative error number on failure.
+ * Return:
+ * * %1: notify the caller that sequence switch is performed to allow it to
+ * setup FLD for it.
+ * * %0: new FID allocated in current sequence.
+ * * %negative: On failure
  */
 int seq_client_alloc_fid(const struct lu_env *env,
                         struct lu_client_seq *seq, struct lu_fid *fid)

diff --git a/lustre/fid/lproc_fid.c b/lustre/fid/lproc_fid.c
index 62a4f75..40d0bc1 100644 (file)
--- a/lustre/fid/lproc_fid.c
+++ b/lustre/fid/lproc_fid.c
@@ -28,7 +28,7 @@
 
 /* Format: [0x64BIT_INT - 0x64BIT_INT] + 32 bytes just in case */
 #define MAX_FID_RANGE_STRLEN (32 + 2 * 2 * sizeof(__u64))
-/**
+/*
  * Reduce the SEQ range allocated to a node to a strict subset of the range
  * currently-allocated SEQ range.  If the specified range is "clear", then
  * drop all allocated sequences and request a new one from the master.