[PATCH] nvme-tcp.h: drop kernel-doc comments, fix a few descriptions

[PATCH] nvme-tcp.h: drop kernel-doc comments, fix a few descriptions

[Randy Dunlap]

Expand @fei into @feil and @feih because the field was split due to it
not being 32-bit aligned.

Struct member @hdr was described twice in struct nvme_tcp_rsp_pdu, so
drop one of them.

These structs are defined in a spec outside of the kernel, so kernel-doc
comments for them aren't needed here as well.

This avoids kernel-doc warnings:

Warning: include/linux/nvme-tcp.h:95 struct member 'rsvd2' not described in 'nvme_tcp_icreq_pdu'
Warning: include/linux/nvme-tcp.h:113 struct member 'rsvd' not described in 'nvme_tcp_icresp_pdu'
Warning: include/linux/nvme-tcp.h:128 struct member 'feil' not described in 'nvme_tcp_term_pdu'
Warning: include/linux/nvme-tcp.h:128 struct member 'feiu' not described in 'nvme_tcp_term_pdu'
Warning: include/linux/nvme-tcp.h:128 struct member 'rsvd' not described in 'nvme_tcp_term_pdu'
Warning: include/linux/nvme-tcp.h:169 struct member 'rsvd' not described in 'nvme_tcp_r2t_pdu'
Warning: include/linux/nvme-tcp.h:187 struct member 'rsvd' not described in 'nvme_tcp_data_pdu'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
v2: drop kernel-doc notation instead of making corrections since the
    format is defined external to the kernel

Cc: Keith Busch <kbusch@kernel.org>
Cc: Jens Axboe <axboe@fb.com>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Sagi Grimberg <sagi@grimberg.me>
Cc: linux-nvme@lists.infradead.org

 include/linux/nvme-tcp.h |   18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

--- linux-next-20260313.orig/include/linux/nvme-tcp.h
+++ linux-next-20260313/include/linux/nvme-tcp.h
@@ -77,7 +77,7 @@ struct nvme_tcp_hdr {
 	__le32	plen;
 };
 
-/**
+/*
  * struct nvme_tcp_icreq_pdu - nvme tcp initialize connection request pdu
  *
  * @hdr:           pdu generic header
@@ -95,7 +95,7 @@ struct nvme_tcp_icreq_pdu {
 	__u8			rsvd2[112];
 };
 
-/**
+/*
  * struct nvme_tcp_icresp_pdu - nvme tcp initialize connection response pdu
  *
  * @hdr:           pdu common header
@@ -113,12 +113,13 @@ struct nvme_tcp_icresp_pdu {
 	__u8			rsvd[112];
 };
 
-/**
+/*
  * struct nvme_tcp_term_pdu - nvme tcp terminate connection pdu
  *
  * @hdr:           pdu common header
  * @fes:           fatal error status
- * @fei:           fatal error information
+ * @feil:          fatal error information (low 16 bits)
+ * @feih:          fatal error information (high 16 bits)
  */
 struct nvme_tcp_term_pdu {
 	struct nvme_tcp_hdr	hdr;
@@ -128,7 +129,7 @@ struct nvme_tcp_term_pdu {
 	__u8			rsvd[10];
 };
 
-/**
+/*
  * struct nvme_tcp_cmd_pdu - nvme tcp command capsule pdu
  *
  * @hdr:           pdu common header
@@ -139,10 +140,9 @@ struct nvme_tcp_cmd_pdu {
 	struct nvme_command	cmd;
 };
 
-/**
+/*
  * struct nvme_tcp_rsp_pdu - nvme tcp response capsule pdu
  *
- * @hdr:           pdu common header
  * @hdr:           nvme-tcp generic header
  * @cqe:           nvme completion queue entry
  */
@@ -151,7 +151,7 @@ struct nvme_tcp_rsp_pdu {
 	struct nvme_completion	cqe;
 };
 
-/**
+/*
  * struct nvme_tcp_r2t_pdu - nvme tcp ready-to-transfer pdu
  *
  * @hdr:           pdu common header
@@ -169,7 +169,7 @@ struct nvme_tcp_r2t_pdu {
 	__u8			rsvd[4];
 };
 
-/**
+/*
  * struct nvme_tcp_data_pdu - nvme tcp data pdu
  *
  * @hdr:           pdu common header

Re: [PATCH] nvme-tcp.h: drop kernel-doc comments, fix a few descriptions

[Christoph Hellwig]

On Fri, Mar 13, 2026 at 09:04:21PM -0700, Randy Dunlap wrote:
> Expand @fei into @feil and @feih because the field was split due to it
> not being 32-bit aligned.
> 
> Struct member @hdr was described twice in struct nvme_tcp_rsp_pdu, so
> drop one of them.
> 
> These structs are defined in a spec outside of the kernel, so kernel-doc
> comments for them aren't needed here as well.
> 
> This avoids kernel-doc warnings:

I would have just dropped the comment entirely except for a reference
to the spec, but let's get the warning fixed instead of bikeshedding
for now:

Reviewed-by: Christoph Hellwig <hch@lst.de>