From: Sean Anderson Date: Wed, 2 Sep 2020 10:56:32 -0400 Subject: [PATCH v5 02/11] pinctrl: Reformat documentation in dm/pinctrl.h In-Reply-To: <205fa639-1b5c-3d9a-ba69-5b41155c211f@gmx.de> References: <20200815155237.467720-1-seanga2@gmail.com> <20200815155237.467720-3-seanga2@gmail.com> <205fa639-1b5c-3d9a-ba69-5b41155c211f@gmx.de> Message-ID: <0154adc6-32f4-e2b2-6503-988d6be60681@gmail.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de 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 >> Reviewed-by: Simon Glass > > > 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