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

Sean Anderson
2020-09-02T15:38:03Z

On 9/2/20 11:17 AM, Heinrich Schuchardt wrote:
> 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.

I also experienced this issue when using fully-qualified names.

>
> Best regards
>
> Heinrich
>
>>
>>
>> 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
>>
>