[PATCH v5 02/11] pinctrl: Reformat documentation in dm/pinctrl.h

Sean Anderson
2020-09-02T14:56:32Z

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-member-documentation-comments
> and
> https://www.kernel.org/doc/html/v5.7/doc-guide/kernel-doc.html#nested-structs-unions

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


pinmux_group: A u32 representing the pin identifier
and mux
settings. The exact format of a pinmux group is left up to the
driver.


However, it should be something like

pinmux_group: A u32 representing the pin identifier
and mux settings. The exact format of a pinmux group is left up to the
driver.

I have also tried an alternate style, as shown for @Return. However,
this too generated the wrong html:


Return:
Pin selector for the muxed pin if OK, or negative error code on
failure


where it should generate something like

Return: Pin selector for the muxed pin
if OK, or negative error code on failure

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/e835cf9552dc96438699806731a208b40daead7b