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,

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.


-/**
+/*
  * 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.

 /**
  * 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.

Thanks,

Bart.

Reply via email to