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

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

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

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