RTRS/rtrs: clean up rtrs headers kernel-doc

Fix all (30+) kernel-doc warnings in rtrs.h and rtrs-pri.h. The changes are:

- add ending ':' to enum member names
- change enum description separators from '-' to ':'
- add "struct" keyword to kernel-doc for structs where missing
- fix enum names in enum rtrs_clt_con_type
- add a '-' separator and drop the "()" in enum rtrs_clt_con_type
- convert struct rtrs_addr to kernel-doc format
- add missing struct member descriptions for struct rtrs_attrs

Signed-off-by Randy Dunlap <[email protected]>

---
Cc: "Md. Haris Iqbal" <[email protected]>
Cc: Jack Wang <[email protected]>
Cc: Jason Gunthorpe <[email protected]>
Cc: Leon Romanovsky <[email protected]>
Cc: [email protected]

---
 drivers/infiniband/ulp/rtrs/rtrs-pri.h |   32 +++++++++++++++--------
 drivers/infiniband/ulp/rtrs/rtrs.h     |   24 ++++++++++-------
 2 files changed, 36 insertions(+), 20 deletions(-)

drivers/infiniband/ulp/rtrs/rtrs.h +15 -9

@@ -24,8 +24,8 @@ struct rtrs_srv_op;
 
 /**
  * enum rtrs_clt_link_ev - Events about connectivity state of a client
- * @RTRS_CLT_LINK_EV_RECONNECTED       Client was reconnected.
- * @RTRS_CLT_LINK_EV_DISCONNECTED      Client was disconnected.
+ * @RTRS_CLT_LINK_EV_RECONNECTED:      Client was reconnected.
+ * @RTRS_CLT_LINK_EV_DISCONNECTED:     Client was disconnected.
  */
 enum rtrs_clt_link_ev {
        RTRS_CLT_LINK_EV_RECONNECTED,

@@ -33,7 +33,9 @@ enum rtrs_clt_link_ev {
 };
 
 /**
- * Source and destination address of a path to be established
+ * struct rtrs_addr - Source and destination address of a path to be established
+ * @src:       source address
+ * @dst:       destination address
  */
 struct rtrs_addr {
        struct sockaddr_storage *src;

@@ -41,7 +43,7 @@ struct rtrs_addr {
 };
 
 /**
- * rtrs_clt_ops - it holds the link event callback and private pointer.
+ * struct rtrs_clt_ops - it holds the link event callback and private pointer.
  * @priv: User supplied private data.
  * @link_ev: Event notification callback function for connection state changes
  *     @priv: User supplied data that was passed to rtrs_clt_open()

@@ -67,10 +69,10 @@ enum wait_type {
 };
 
 /**
- * enum rtrs_clt_con_type() type of ib connection to use with a given
+ * enum rtrs_clt_con_type - type of ib connection to use with a given
  * rtrs_permit
- * @ADMIN_CON - use connection reserved for "service" messages
- * @IO_CON - use a connection reserved for IO
+ * @RTRS_ADMIN_CON: use connection reserved for "service" messages
+ * @RTRS_IO_CON: use a connection reserved for IO
  */
 enum rtrs_clt_con_type {
        RTRS_ADMIN_CON,

@@ -85,7 +87,7 @@ void rtrs_clt_put_permit(struct rtrs_clt
                         struct rtrs_permit *permit);
 
 /**
- * rtrs_clt_req_ops - it holds the request confirmation callback
+ * struct rtrs_clt_req_ops - it holds the request confirmation callback
  * and a private pointer.
  * @priv: User supplied private data.
  * @conf_fn:   callback function to be called as confirmation

@@ -105,7 +107,11 @@ int rtrs_clt_request(int dir, struct rtr
 int rtrs_clt_rdma_cq_direct(struct rtrs_clt_sess *clt, unsigned int index);
 
 /**
- * rtrs_attrs - RTRS session attributes
+ * struct rtrs_attrs - RTRS session attributes
+ * @queue_depth:       queue_depth saved from rtrs_clt_sess message
+ * @max_io_size:       max_io_size from rtrs_clt_sess message, capped to
+ *                       @max_segments * %SZ_4K
+ * @max_segments:      max_segments saved from rtrs_clt_sess message
  */
 struct rtrs_attrs {
        u32             queue_depth;

drivers/infiniband/ulp/rtrs/rtrs-pri.h +21 -11

@@ -150,7 +150,7 @@ enum rtrs_msg_types {
 
 /**
  * enum rtrs_msg_flags - RTRS message flags.
- * @RTRS_NEED_INVAL:   Send invalidation in response.
+ * @RTRS_MSG_NEED_INVAL_F: Send invalidation in response.
  * @RTRS_MSG_NEW_RKEY_F: Send refreshed rkey in response.
  */
 enum rtrs_msg_flags {

@@ -179,16 +179,19 @@ struct rtrs_sg_desc {
  * @recon_cnt:    Reconnections counter
  * @sess_uuid:    UUID of a session (path)
  * @paths_uuid:           UUID of a group of sessions (paths)
- *
+ * @first_conn:    %1 if the connection request is the first for that session,
+ *                     otherwise %0
  * NOTE: max size 56 bytes, see man rdma_connect().
  */
 struct rtrs_msg_conn_req {
-       /* Is set to 0 by cma.c in case of AF_IB, do not touch that.
-        * see https://www.spinics.net/lists/linux-rdma/msg22397.html
+       /**
+        * @__cma_version: Is set to 0 by cma.c in case of AF_IB, do not touch
+        * that. See https://www.spinics.net/lists/linux-rdma/msg22397.html
         */
        u8              __cma_version;
-       /* On sender side that should be set to 0, or cma_save_ip_info()
-        * extract garbage and will fail.
+       /**
+        * @__ip_version: On sender side that should be set to 0, or
+        * cma_save_ip_info() extract garbage and will fail.
         */
        u8              __ip_version;
        __le16          magic;

@@ -199,6 +202,7 @@ struct rtrs_msg_conn_req {
        uuid_t          sess_uuid;
        uuid_t          paths_uuid;
        u8              first_conn : 1;
+       /* private: */
        u8              reserved_bits : 7;
        u8              reserved[11];
 };

@@ -211,6 +215,7 @@ struct rtrs_msg_conn_req {
  * @queue_depth:   max inflight messages (queue-depth) in this session
  * @max_io_size:   max io size server supports
  * @max_hdr_size:  max msg header size server supports
+ * @flags:        RTRS message flags for this message
  *
  * NOTE: size is 56 bytes, max possible is 136 bytes, see man rdma_accept().
  */

@@ -222,22 +227,24 @@ struct rtrs_msg_conn_rsp {
        __le32          max_io_size;
        __le32          max_hdr_size;
        __le32          flags;
+       /* private: */
        u8              reserved[36];
 };
 
 /**
- * struct rtrs_msg_info_req
+ * struct rtrs_msg_info_req - client additional info request
  * @type:              @RTRS_MSG_INFO_REQ
  * @pathname:          Path name chosen by client
  */
 struct rtrs_msg_info_req {
        __le16          type;
        u8              pathname[NAME_MAX];
+       /* private: */
        u8              reserved[15];
 };
 
 /**
- * struct rtrs_msg_info_rsp
+ * struct rtrs_msg_info_rsp - server additional info response
  * @type:              @RTRS_MSG_INFO_RSP
  * @sg_cnt:            Number of @desc entries
  * @desc:              RDMA buffers where the client can write to server

@@ -245,12 +252,14 @@ struct rtrs_msg_info_req {
 struct rtrs_msg_info_rsp {
        __le16          type;
        __le16          sg_cnt;
+       /* private: */
        u8              reserved[4];
+       /* public: */
        struct rtrs_sg_desc desc[];
 };
 
 /**
- * struct rtrs_msg_rkey_rsp
+ * struct rtrs_msg_rkey_rsp - server refreshed rkey response
  * @type:              @RTRS_MSG_RKEY_RSP
  * @buf_id:            RDMA buf_id of the new rkey
  * @rkey:              new remote key for RDMA buffers id from server

@@ -264,6 +273,7 @@ struct rtrs_msg_rkey_rsp {
 /**
  * struct rtrs_msg_rdma_read - RDMA data transfer request from client
  * @type:              always @RTRS_MSG_READ
+ * @flags:             RTRS message flags (enum rtrs_msg_flags)
  * @usr_len:           length of user payload
  * @sg_cnt:            number of @desc entries
  * @desc:              RDMA buffers where the server can write the result to

@@ -277,7 +287,7 @@ struct rtrs_msg_rdma_read {
 };
 
 /**
- * struct_msg_rdma_write - Message transferred to server with RDMA-Write
+ * struct rtrs_msg_rdma_write - Message transferred to server with RDMA-Write
  * @type:              always @RTRS_MSG_WRITE
  * @usr_len:           length of user payload
  */

@@ -287,7 +297,7 @@ struct rtrs_msg_rdma_write {
 };
 
 /**
- * struct_msg_rdma_hdr - header for read or write request
+ * struct rtrs_msg_rdma_hdr - header for read or write request
  * @type:              @RTRS_MSG_WRITE | @RTRS_MSG_READ
  */
 struct rtrs_msg_rdma_hdr {

Fix all (30+) kernel-doc warnings in rtrs.h and rtrs-pri.h. The changes are:

- add ending ':' to enum member names
- change enum description separators from '-' to ':'
- add "struct" keyword to kernel-doc for structs where missing
- fix enum names in enum rtrs_clt_con_type
- add a '-' separator and drop the "()" in enum rtrs_clt_con_type
- convert struct rtrs_addr to kernel-doc format
- add missing struct member descriptions for struct rtrs_attrs

Signed-off-by Randy Dunlap <[email protected]>

Acked-by Jack Wang <[email protected]>

---
Cc: "Md. Haris Iqbal" <[email protected]>
Cc: Jack Wang <[email protected]>
Cc: Jason Gunthorpe <[email protected]>
Cc: Leon Romanovsky <[email protected]>
Cc: [email protected]

---
 drivers/infiniband/ulp/rtrs/rtrs-pri.h |   32 +++++++++++++++--------
 drivers/infiniband/ulp/rtrs/rtrs.h     |   24 ++++++++++-------
 2 files changed, 36 insertions(+), 20 deletions(-)