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 <[email protected]> >>>> Reviewed-by: Simon Glass <[email protected]> >>> >>> >>> 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 > >> >> <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 >> >
