On 02.09.20 16:56, Sean Anderson wrote:
On 9/2/20 8:26 AM, Heinrich Schuchardt wrote:
On 15.08.20 17:52, Sean Anderson wrote:
This normalizes the documentatation to conform to kernel-doc style [1]. It
Nits: %s/documentatation/documentation/
also moves the documentation for pinctrl_ops inline, and adds argument and return-value documentation. I have kept the usual function style for these comments. I could not find any existing examples of function documentation inside structs.
[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
Signed-off-by: Sean Anderson seanga2@gmail.com Reviewed-by: Simon Glass sjg@chromium.org
Before and after this patch the documentation format is incorrect. See output below for the situation after the patch.
Please include include/dm/pinctrl.h into doc/api/index.rst via a new file doc/api/pnctrl.rst.
A documentation style accepted by 'make htmldocs' is:
struct pinctrl_ops { /** * @get_pins_count: Get the number of selectable pins * * @get_pins_count.dev: Pinctrl device to use * * This function is necessary to parse the "pins" property * in DTS. * * @get_pins_count.Return: number of selectable named pins * available in this driver */ int (*get_pins_count)(struct udevice *dev);
See the nested structures in
https://www.kernel.org/doc/html/v5.7/doc-guide/kernel-doc.html#in-line-membe... and https://www.kernel.org/doc/html/v5.7/doc-guide/kernel-doc.html#nested-struct...
Thanks for suggesting those changes. This works better. As far as I can tell, fully-qualified members are only necessary when documenting nested structs at the top-level. When using in-line documentation, members are automatically nested. With that in mind, I am using the following format
/** * @pinmux_property_set: Enable a pinmux group * * @dev: Pinctrl device to use * * @pinmux_group: A u32 representing the pin identifier and mux * settings. The exact format of a pinmux group is left * up to the driver. * * Mux a single pin to a single function based on a driver-specific * pinmux group. This function is necessary for parsing the "pinmux" * property in DTS, and for pin-muxing against a pinmux group. * * @Return: * Pin selector for the muxed pin if OK, or negative error code on * failure */ int (*pinmux_property_set)(struct udevice *dev, u32 pinmux_group);
However, I am having some problems with multi-line descriptions. In the example above, the desciption for @pinmux_group has the first line bolded and the rest of the description is typeset as normal, but is indented. The generated html is
Use fully qualified names and you are fine.
Best regards
Heinrich
<dl class="docutils"> <dt><strong>pinmux_group</strong>: A u32 representing the pin identifier and mux</dt> <dd>settings. The exact format of a pinmux group is left up to the driver.</dd> </dl>
However, it should be something like
<p><strong>pinmux_group</strong>: A u32 representing the pin identifier and mux settings. The exact format of a pinmux group is left up to the driver.</p>
I have also tried an alternate style, as shown for @Return. However, this too generated the wrong html:
<dl class="last docutils"> <dt><strong>Return</strong>:</dt> <dd>Pin selector for the muxed pin if OK, or negative error code on failure</dd> </dl>
where it should generate something like
<p class="last"><strong>Return</strong>: Pin selector for the muxed pin if OK, or negative error code on failure</p>
Do you have any suggestions for generating the latter forms? My current work is at [1].
--Sean
[1] https://github.com/Forty-Bot/u-boot/commit/e835cf9552dc96438699806731a208b40...