LU-9633 ptlrpc: Add kernel doc style for ptlrpc (8)

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: I9a9df9e1deb1a5c59d21da0af5b622038e2c8762
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58864
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Petros Koutoupis <petros.koutoupis@hpe.com>
Reviewed-by: Anjus George <georgea@ornl.gov>
Reviewed-by: James Simmons <jsimmons@infradead.org>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/ptlrpc/lproc_ptlrpc.c b/lustre/ptlrpc/lproc_ptlrpc.c
index a4b002b..80b43fa 100644 (file)
--- a/lustre/ptlrpc/lproc_ptlrpc.c
+++ b/lustre/ptlrpc/lproc_ptlrpc.c
@@ -452,9 +452,10 @@ static ssize_t threads_max_store(struct kobject *kobj, struct attribute *attr,
 LUSTRE_RW_ATTR(threads_max);
 
 /**
- * Translates \e ptlrpc_nrs_pol_state values to human-readable strings.
+ * nrs_state2str() - Translates @state values to human-readable strings.
+ * @state: The policy state
  *
- * \param[in] state The policy state
+ * Returns char *(string) correspoding to @state or NULl
  */
 static const char *nrs_state2str(enum ptlrpc_nrs_pol_state state)
 {
@@ -476,12 +477,11 @@ static const char *nrs_state2str(enum ptlrpc_nrs_pol_state state)
 }
 
 /**
- * Obtains status information for \a policy.
+ * nrs_policy_get_info_locked() - Obtains status information for @policy.
+ * @policy: The policy
+ * @info: Holds returned status information [out]
  *
- * Information is copied in \a info.
- *
- * \param[in] policy The policy
- * \param[out] info  Holds returned status information
+ * Information is copied in @info.
  */
 static void nrs_policy_get_info_locked(struct ptlrpc_nrs_policy *policy,
                                       struct ptlrpc_nrs_pol_info *info)
@@ -504,7 +504,7 @@ static void nrs_policy_get_info_locked(struct ptlrpc_nrs_policy *policy,
        info->pi_req_started = policy->pol_req_started;
 }
 
-/**
+/*
  * Reads and prints policy status information for all policies of a PTLRPC
  * service.
  */
@@ -689,14 +689,14 @@ out:
 }
 
 #define LPROCFS_NRS_WR_MAX_ARG (1024)
-/**
+/*
  * The longest valid command string is the maxium policy name size, plus the
  * length of the " reg" substring, plus the lenght of argument
  */
 #define LPROCFS_NRS_WR_MAX_CMD (NRS_POL_NAME_MAX + sizeof(" reg") - 1 + \
                                LPROCFS_NRS_WR_MAX_ARG)
 
-/**
+/*
  * Starts and stops a given policy on a PTLRPC service.
  *
  * Commands consist of the policy name, followed by an optional [reg|hp] token;

diff --git a/lustre/ptlrpc/nodemap_member.c b/lustre/ptlrpc/nodemap_member.c
index 0f338b9..d25243e 100644 (file)
--- a/lustre/ptlrpc/nodemap_member.c
+++ b/lustre/ptlrpc/nodemap_member.c
@@ -17,13 +17,14 @@
 
 
 /**
+ * nm_member_del() - Delete an export from a nodemap's member list
+ * @nodemap: nodemap containing list
+ * @exp: export member to delete
+ *
  * Delete an export from a nodemap's member list. Called after client
  * disconnects, or during system shutdown.
  *
- * Requires active_config_lock and nodemap's nm_member_list_lock.
- *
- * \param      nodemap         nodemap containing list
- * \param      exp             export member to delete
+ * Note: Requires active_config_lock and nodemap's nm_member_list_lock.
  */
 void nm_member_del(struct lu_nodemap *nodemap, struct obd_export *exp)
 {
@@ -49,11 +50,10 @@ void nm_member_del(struct lu_nodemap *nodemap, struct obd_export *exp)
 }
 
 /**
- * Delete a member list from a nodemap
+ * nm_member_delete_list() - Delete a member list from a nodemap
+ * @nodemap: nodemap to remove the list from
  *
  * Requires active config lock.
- *
- * \param      nodemap         nodemap to remove the list from
  */
 void nm_member_delete_list(struct lu_nodemap *nodemap)
 {
@@ -68,14 +68,16 @@ void nm_member_delete_list(struct lu_nodemap *nodemap)
 }
 
 /**
- * Add a member export to a nodemap
+ * nm_member_add() - Add a member export to a nodemap
+ * @nodemap: nodemap to add to
+ * @exp: obd_export to add
  *
  * Must be called under active_config_lock.
  *
- * \param      nodemap         nodemap to add to
- * \param      exp             obd_export to add
- * \retval     -EEXIST         export is already part of a different nodemap
- * \retval     -EINVAL         export is NULL
+ * Return:
+ * * %0 on sucessful add
+ * * %-EEXIST export is already part of a different nodemap
+ * * %-EINVAL export is NULL
  */
 int nm_member_add(struct lu_nodemap *nodemap, struct obd_export *exp)
 {
@@ -119,7 +121,7 @@ int nm_member_add(struct lu_nodemap *nodemap, struct obd_export *exp)
        RETURN(0);
 }
 
-/**
+/*
  * Revokes the locks on an export if it is attached to an MDT and not in
  * recovery. As a performance enhancement, the lock revoking process could
  * revoke only the locks that cover files affected by the nodemap change.
@@ -136,6 +138,9 @@ static void nm_member_exp_revoke(struct obd_export *exp)
 }
 
 /**
+ * nm_member_reclassify_nodemap() - Reclassify members of a nodemap
+ * @nodemap: nodemap with members to reclassify
+ *
  * Reclassify the members of a nodemap after range changes or activation.
  * This function reclassifies the members of a nodemap based on the member
  * export's NID and the nodemap's new NID ranges. Exports that are no longer
@@ -144,8 +149,6 @@ static void nm_member_exp_revoke(struct obd_export *exp)
  *
  * Callers should hold the active_config_lock and active_config
  * nmc_range_tree_lock.
- *
- * \param      nodemap         nodemap with members to reclassify
  */
 void nm_member_reclassify_nodemap(struct lu_nodemap *nodemap)
 {
@@ -209,13 +212,13 @@ void nm_member_reclassify_nodemap(struct lu_nodemap *nodemap)
 }
 
 /**
- * Revoke the locks for member exports if nodemap system is active.
+ * nm_member_revoke_locks() - Revoke the locks for member exports if nodemap
+ * system is active.
+ * @nodemap: nodemap that has been altered
  *
  * Changing the idmap is akin to deleting the security context. If the locks
  * are not canceled, the client could cache permissions that are no longer
  * correct with the map.
- *
- * \param      nodemap         nodemap that has been altered
  */
 void nm_member_revoke_locks(struct lu_nodemap *nodemap)
 {