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

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: I21532bbcb07b00dfb6275f5cd25015b46564c745
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58863
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Marc Vef <mvef@whamcloud.com>
Reviewed-by: Petros Koutoupis <petros.koutoupis@hpe.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/ptlrpc/nodemap_idmap.c b/lustre/ptlrpc/nodemap_idmap.c
index b31fc8c..73007ec 100644 (file)
--- a/lustre/ptlrpc/nodemap_idmap.c
+++ b/lustre/ptlrpc/nodemap_idmap.c
@@ -13,12 +13,11 @@
 #include "nodemap_internal.h"
 
 /**
- * Allocate the lu_idmap structure
+ * idmap_create() - Allocate the lu_idmap structure
+ * @client_id: client uid or gid
+ * @fs_id: filesystem uid or gid
  *
- * \param      client_id               client uid or gid
- * \param      fs_id                   filesystem uid or gid
- *
- * \retval     alloated lu_idmap structure on success, NULL otherwise
+ * Return alloated lu_idmap structure on success, NULL otherwise
  */
 struct lu_idmap *idmap_create(__u32 client_id, __u32 fs_id)
 {
@@ -47,18 +46,18 @@ static void idmap_destroy(struct lu_idmap *idmap)
 }
 
 /**
- * Insert idmap into the proper trees
- *
- * \param      id_type         NODEMAP_UID or NODEMAP_GID or NODEMAP_PROJID
- * \param      idmap           lu_idmap structure to insert
- * \param      nodemap         nodemap to associate with the map
+ * idmap_insert() - Insert idmap into the proper trees
+ * @id_type: NODEMAP_UID or NODEMAP_GID or NODEMAP_PROJID
+ * @idmap: lu_idmap structure to insert
+ * @nodemap: nodemap to associate with the map
  *
- * \retval     NULL             on success
- * \retval     ERR_PTR(-EEXIST) if this idmap already exists
- * \retval     struct lu_idmap  if only id_client or id_fs of this idmap
- *                              is matched, return the matched idmap.
- *                              The caller will delete this old idmap and
- *                              its index before insert the new idmap again.
+ * Return:
+ * * %NULL              on success
+ * * %ERR_PTR(-EEXIST) if this idmap already exists
+ * * %struct lu_idmap   if only id_client or id_fs of this idmap
+ *                      is matched, return the matched idmap.
+ *                      The caller will delete this old idmap and
+ *                      its index before insert the new idmap again.
  */
 struct lu_idmap *idmap_insert(enum nodemap_id_type id_type,
                              struct lu_idmap *idmap,
@@ -149,12 +148,10 @@ struct lu_idmap *idmap_insert(enum nodemap_id_type id_type,
 }
 
 /**
- * Delete idmap from the correct nodemap tree
- *
- * \param      node_type               0 for UID
- *                                     1 for GID
- * \param      idmap                   idmap to delete
- * \param      nodemap                 assoicated idmap
+ * idmap_delete() - Delete idmap from the correct nodemap tree
+ * @id_type: 0 for UID and 1 for GID
+ * @idmap: idmap to delete
+ * @nodemap: assoicated idmap
  */
 void idmap_delete(enum nodemap_id_type id_type, struct lu_idmap *idmap,
                  struct lu_nodemap *nodemap)
@@ -182,16 +179,14 @@ void idmap_delete(enum nodemap_id_type id_type, struct lu_idmap *idmap,
 }
 
 /**
- * Search for an existing id in the nodemap trees.
- *
- * \param      nodemap         nodemap trees to search
- * \param      tree_type       0 for filesystem to client maps
- *                             1 for client to filesystem maps
- * \param      id_type         0 for UID
- *                             1 for GID
- * \param      id              numeric id for which to search
+ * idmap_search() - Search for an existing id in the nodemap trees.
+ * @nodemap: nodemap trees to search
+ * @tree_type: 0 for filesystem to client maps
+ *             1 for client to filesystem maps
+ * @id_type: 0 for UID or 1 for GID
+ * @id: numeric id for which to search
  *
- * \retval     lu_idmap structure with the map on success
+ * Returns lu_idmap structure with the map on success
  */
 struct lu_idmap *idmap_search(struct lu_nodemap *nodemap,
                              enum nodemap_tree_type tree_type,

diff --git a/lustre/ptlrpc/recover.c b/lustre/ptlrpc/recover.c
index 82c2c5b..a1ee178 100644 (file)
--- a/lustre/ptlrpc/recover.c
+++ b/lustre/ptlrpc/recover.c
@@ -26,7 +26,7 @@
 
 #include "ptlrpc_internal.h"
 
-/**
+/*
  * Identify what request from replay list needs to be replayed next
  * (based on what we have already replayed) and send it to server.
  */
@@ -135,7 +135,7 @@ int ptlrpc_replay_next(struct obd_import *imp, int *inflight)
        RETURN(rc);
 }
 
-/**
+/*
  * Schedule resending of request on sending_list. This is done after
  * we completed replaying of requests and locks.
  */
@@ -175,7 +175,7 @@ int ptlrpc_resend(struct obd_import *imp)
        RETURN(0);
 }
 
-/**
+/*
  * Go through all requests in delayed list and wake their threads
  * for resending
  */
@@ -219,11 +219,18 @@ void ptlrpc_request_handle_notconn(struct ptlrpc_request *failed_req)
 }
 
 /**
- * Administratively active/deactive a client.
+ * ptlrpc_set_import_active() - Administratively active/deactive a client.
+ * @imp: import object
+ * @active: flag to activate(1) or de-activate(0)
+ *
  * This should only be called by the ioctl interface, currently
  *  - the lctl deactivate and activate commands
  *  - echo 0/1 >> /proc/osc/XXX/active
  *  - client umount -f (ll_umount_begin)
+ *
+ * Returns:
+ * * %0 on successful activation/deactivation
+ * * %negative on failure
  */
 int ptlrpc_set_import_active(struct obd_import *imp, int active)
 {