On 13/02/2018 17:49, Bart Van Assche wrote:
On 02/13/18 02:17, John Garry wrote:
On 12/02/2018 18:45, Bart Van Assche wrote:
[ ... ]
  * sas_init_disc -- initialize the discovery struct in the port
  * @port: pointer to struct port

I wonder why you get no complaint that @disc argument is not mentioned,

Hi Bart,

Hello John,

Since I was not sure how to document the 'disc' argument I changed /**
into /* to make the kernel-doc tool skip the sas_init_disc() function.
Any suggestion for how to document the 'disc' argument would be welcome.

I see now.

For this @disc pointer, I would just write "port discovery structure".

In fact I think that we could just change the code to accept the @port argument, as the @disc argument is the port->disc. But that's another job.

  * sas_configure_parent -- configure routing table of parent
- * parent: parent expander
- * child: child expander
- * sas_addr: SAS port identifier of device directly attached to child
+ * @parent: parent expander
+ * @child: child expander
+ * @sas_addr: SAS port identifier of device directly attached to child

and no mention of @include here

Also for the 'include' argument, a suggestion of how to document it
would be welcome.

To be honest, I am not so fimilar with this specific part of the code.

As I see, the @include argument is to flag whether we want to setup or tear down a routing for parent (upstream) expander device.

I am not 100% sure on this so you could stick with making it a non-kerneldoc comments. It is static.

  * sas_revalidate_domain -- revalidate the domain

This function name seems incorrect. [ ... ]  And I would write "port
domain device"

Thanks, will fix.


If the build does not complain about this for W=1, then should we
include it? I ask, as I see many other instances of "/**". I don't
mind cleaning them up in a separate patch.

The kernel-doc tool only analyzes function headers that start with
"/**". Any changes of "/**" into "/*" mean that I did not know how to
document the arguments about which the kernel-doc tool complained that
documentation was missing.





Reply via email to