[06/12] infiniband: fix ulp/srpt/ib_srpt.h kernel-doc notation
diff mbox series

Message ID 20191010035239.950150496@gmail.com
State Accepted
Delegated to: Jason Gunthorpe
Headers show
Series
  • infiniband kernel-doc fixes & driver-api/ chapter
Related show

Commit Message

Randy Dunlap Oct. 10, 2019, 3:52 a.m. UTC
Fix kernel-doc warnings (typos or renames) in ib_srpt.h:

../drivers/infiniband/ulp/srpt/ib_srpt.h:419: warning: Function parameter or member 'port_guid_id' not described in 'srpt_port'
../drivers/infiniband/ulp/srpt/ib_srpt.h:419: warning: Function parameter or member 'port_gid_id' not described in 'srpt_port'

Signed-off-by: Randy Dunlap <rd.dunlab@gmail.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Doug Ledford <dledford@redhat.com>
Cc: Jason Gunthorpe <jgg@mellanox.com>
Cc: linux-doc@vger.kernel.org
---
 drivers/infiniband/ulp/srpt/ib_srpt.h |    7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

Comments

Bart Van Assche Oct. 23, 2019, 8:30 p.m. UTC | #1
On 2019-10-09 20:52, rd.dunlab@gmail.com wrote:
> --- linux-next-20191009.orig/drivers/infiniband/ulp/srpt/ib_srpt.h
> +++ linux-next-20191009/drivers/infiniband/ulp/srpt/ib_srpt.h
> @@ -387,12 +387,9 @@ struct srpt_port_id {
>   * @sm_lid:    cached value of the port's sm_lid.
>   * @lid:       cached value of the port's lid.
>   * @gid:       cached value of the port's gid.
> - * @port_acl_lock spinlock for port_acl_list:
>   * @work:      work structure for refreshing the aforementioned cached values.
> - * @port_guid_tpg: TPG associated with target port GUID.
> - * @port_guid_wwn: WWN associated with target port GUID.
> - * @port_gid_tpg:  TPG associated with target port GID.
> - * @port_gid_wwn:  WWN associated with target port GID.
> + * @port_guid_id: target port GUID
> + * @port_gid_id: target port GID
>   * @port_attrib:   Port attributes that can be accessed through configfs.
>   * @refcount:	   Number of objects associated with this port.
>   * @freed_channels: Completion that will be signaled once @refcount becomes 0.

This is sufficient to silence the warnings reported by the kernel-doc
tool but I don't think that the new descriptions make really clear what
these structure members represent. Do you want to address this or do you
expect me to post a follow-up patch?

Thanks,

Bart.
Randy Dunlap Oct. 23, 2019, 8:39 p.m. UTC | #2
On 10/23/19 1:30 PM, Bart Van Assche wrote:
> On 2019-10-09 20:52, rd.dunlab@gmail.com wrote:
>> --- linux-next-20191009.orig/drivers/infiniband/ulp/srpt/ib_srpt.h
>> +++ linux-next-20191009/drivers/infiniband/ulp/srpt/ib_srpt.h
>> @@ -387,12 +387,9 @@ struct srpt_port_id {
>>   * @sm_lid:    cached value of the port's sm_lid.
>>   * @lid:       cached value of the port's lid.
>>   * @gid:       cached value of the port's gid.
>> - * @port_acl_lock spinlock for port_acl_list:
>>   * @work:      work structure for refreshing the aforementioned cached values.
>> - * @port_guid_tpg: TPG associated with target port GUID.
>> - * @port_guid_wwn: WWN associated with target port GUID.
>> - * @port_gid_tpg:  TPG associated with target port GID.
>> - * @port_gid_wwn:  WWN associated with target port GID.
>> + * @port_guid_id: target port GUID
>> + * @port_gid_id: target port GID
>>   * @port_attrib:   Port attributes that can be accessed through configfs.
>>   * @refcount:	   Number of objects associated with this port.
>>   * @freed_channels: Completion that will be signaled once @refcount becomes 0.
> 
> This is sufficient to silence the warnings reported by the kernel-doc
> tool but I don't think that the new descriptions make really clear what
> these structure members represent. Do you want to address this or do you
> expect me to post a follow-up patch?

Hi Bart,

Since you know what the descriptions should say, I would appreciate it if you
would post a follow-up patch.

Thanks.

Patch
diff mbox series

--- linux-next-20191009.orig/drivers/infiniband/ulp/srpt/ib_srpt.h
+++ linux-next-20191009/drivers/infiniband/ulp/srpt/ib_srpt.h
@@ -387,12 +387,9 @@  struct srpt_port_id {
  * @sm_lid:    cached value of the port's sm_lid.
  * @lid:       cached value of the port's lid.
  * @gid:       cached value of the port's gid.
- * @port_acl_lock spinlock for port_acl_list:
  * @work:      work structure for refreshing the aforementioned cached values.
- * @port_guid_tpg: TPG associated with target port GUID.
- * @port_guid_wwn: WWN associated with target port GUID.
- * @port_gid_tpg:  TPG associated with target port GID.
- * @port_gid_wwn:  WWN associated with target port GID.
+ * @port_guid_id: target port GUID
+ * @port_gid_id: target port GID
  * @port_attrib:   Port attributes that can be accessed through configfs.
  * @refcount:	   Number of objects associated with this port.
  * @freed_channels: Completion that will be signaled once @refcount becomes 0.