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.
