Messages in this thread Patch in this message | | | Date | Wed, 11 Mar 2020 17:49:44 -0700 | From | Matthew Wilcox <> | Subject | Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. |
| |
On Wed, Mar 11, 2020 at 07:28:23PM +0000, peter@bikeshed.quignogs.org.uk wrote: > Added line breaks and blank lines to separate list items and escaped end-of-line > colons. > > This removes these warnings from doc build... > > ./drivers/net/phy/sfp-bus.c:579: WARNING: Unexpected indentation. > ./drivers/net/phy/sfp-bus.c:619: WARNING: Unexpected indentation.
I'm all in favour of removing warnings, but I think you've fixed this the wrong way.
> @@ -572,12 +572,18 @@ static void sfp_upstream_clear(struct sfp_bus *bus) > * the sfp_bus structure, incrementing its reference count. This must > * be put via sfp_bus_put() when done. > * > - * Returns: on success, a pointer to the sfp_bus structure, > + * Returns\:
This should be Return: (not Returns:) and marks a section header, not the beginning of the list. See the "Return values" section in Documentation/doc-guide/kernel-doc.rst
> + * > + * on success, a pointer to the sfp_bus structure, > * %NULL if no SFP is specified, > + * > * on failure, an error pointer value: > + * > * corresponding to the errors detailed for > * fwnode_property_get_reference_args(). > + * > * %-ENOMEM if we failed to allocate the bus. > + * > * an error from the upstream's connect_phy() method.
Seems to me this should use the " * * VALUE - Description" format described in the document I mentioned above.
| |