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 <sean...@gmail.com> >>> Reviewed-by: Simon Glass <s...@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 >
