* [PATCH 0/1] Convert text to ReST list and remove doc build warnings @ 2020-03-11 19:28 peter 2020-03-11 19:28 ` [PATCH 1/1] Reformat return value descriptions as ReST lists peter 0 siblings, 1 reply; 6+ messages in thread From: peter @ 2020-03-11 19:28 UTC (permalink / raw) To: linux-doc, netdev Cc: Russell King, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> A minimal patch to format a couple of multi-line return value descriptions as ReST lists, mostly by adding blank lines to kerneldoc comments. This is pure formatting - the actual documentation text remains unchanged. It also removes a couple of warnings from the doc build. Peter Lister (1): Reformat return value descriptions as ReST lists. drivers/net/phy/sfp-bus.c | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) -- 2.24.1 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/1] Reformat return value descriptions as ReST lists. 2020-03-11 19:28 [PATCH 0/1] Convert text to ReST list and remove doc build warnings peter @ 2020-03-11 19:28 ` peter 2020-03-11 20:38 ` Russell King - ARM Linux admin 2020-03-12 0:49 ` Matthew Wilcox 0 siblings, 2 replies; 6+ messages in thread From: peter @ 2020-03-11 19:28 UTC (permalink / raw) To: linux-doc, netdev Cc: Russell King, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> 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. Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> --- drivers/net/phy/sfp-bus.c | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/drivers/net/phy/sfp-bus.c b/drivers/net/phy/sfp-bus.c index d949ea7b4f8c..df1c66df830f 100644 --- a/drivers/net/phy/sfp-bus.c +++ b/drivers/net/phy/sfp-bus.c @@ -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\: + * + * 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. */ struct sfp_bus *sfp_bus_find_fwnode(struct fwnode_handle *fwnode) @@ -612,12 +618,18 @@ EXPORT_SYMBOL_GPL(sfp_bus_find_fwnode); * the SFP bus using sfp_register_upstream(). This takes a reference on the * bus, so it is safe to put the bus after this call. * - * Returns: on success, a pointer to the sfp_bus structure, + * Returns\: + * + * 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. */ int sfp_bus_add_upstream(struct sfp_bus *bus, void *upstream, -- 2.24.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. 2020-03-11 19:28 ` [PATCH 1/1] Reformat return value descriptions as ReST lists peter @ 2020-03-11 20:38 ` Russell King - ARM Linux admin 2020-03-11 22:21 ` Peter Lister 2020-03-12 0:49 ` Matthew Wilcox 1 sibling, 1 reply; 6+ messages in thread From: Russell King - ARM Linux admin @ 2020-03-11 20:38 UTC (permalink / raw) To: peter Cc: linux-doc, netdev, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel On Wed, Mar 11, 2020 at 07:28:23PM +0000, peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > 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. > > Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> > --- > drivers/net/phy/sfp-bus.c | 16 ++++++++++++++-- > 1 file changed, 14 insertions(+), 2 deletions(-) > > diff --git a/drivers/net/phy/sfp-bus.c b/drivers/net/phy/sfp-bus.c > index d949ea7b4f8c..df1c66df830f 100644 > --- a/drivers/net/phy/sfp-bus.c > +++ b/drivers/net/phy/sfp-bus.c > @@ -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\: > + * > + * 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. Is this really necessary? This seems to be rather OTT, and makes the comment way too big IMHO. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. 2020-03-11 20:38 ` Russell King - ARM Linux admin @ 2020-03-11 22:21 ` Peter Lister 2020-03-11 22:25 ` Russell King - ARM Linux admin 0 siblings, 1 reply; 6+ messages in thread From: Peter Lister @ 2020-03-11 22:21 UTC (permalink / raw) To: Russell King - ARM Linux admin Cc: linux-doc, netdev, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel Hello Russell, > Is this really necessary? This seems to be rather OTT, and makes the > comment way too big IMHO. The existing form definitely gets the formatted output wrong (I'll send you a screen grab if you like) and causes doc build warnings. So, yes, it needs fixing. ReST makes free with blank lines round blocks and list entries, and I agree this makes for inelegant source annotation. I tried to retain the wording unchanged and present the description as just "whitespace" changes to make a list in the formatted output - as close as I could to what the author appears to intend. If you're OK with a mild rewrite of the return value description, e.g. as two sentences (On success: p; q. On failure: x; y; z.), then we can fix the doc build and have terser source comments and a happier kerneldoc. All the best, Peter Lister ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. 2020-03-11 22:21 ` Peter Lister @ 2020-03-11 22:25 ` Russell King - ARM Linux admin 0 siblings, 0 replies; 6+ messages in thread From: Russell King - ARM Linux admin @ 2020-03-11 22:25 UTC (permalink / raw) To: Peter Lister Cc: linux-doc, netdev, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel On Wed, Mar 11, 2020 at 10:21:41PM +0000, Peter Lister wrote: > Hello Russell, > > > Is this really necessary? This seems to be rather OTT, and makes the > > comment way too big IMHO. > > The existing form definitely gets the formatted output wrong (I'll send you > a screen grab if you like) and causes doc build warnings. So, yes, it needs > fixing. > > ReST makes free with blank lines round blocks and list entries, and I agree > this makes for inelegant source annotation. I tried to retain the wording > unchanged and present the description as just "whitespace" changes to make a > list in the formatted output - as close as I could to what the author > appears to intend. > > If you're OK with a mild rewrite of the return value description, e.g. as > two sentences (On success: p; q. On failure: x; y; z.), then we can fix the > doc build and have terser source comments and a happier kerneldoc. I think it's more important that the documentation interferes to a minimal degree with the code in the file, so please rewrite if it improves it. (btw, I'm the author.) Thanks. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. 2020-03-11 19:28 ` [PATCH 1/1] Reformat return value descriptions as ReST lists peter 2020-03-11 20:38 ` Russell King - ARM Linux admin @ 2020-03-12 0:49 ` Matthew Wilcox 1 sibling, 0 replies; 6+ messages in thread From: Matthew Wilcox @ 2020-03-12 0:49 UTC (permalink / raw) To: peter Cc: linux-doc, netdev, Russell King, Andrew Lunn, Florian Fainelli, Heiner Kallweit, Jonathan Corbet, linux-kernel 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-03-12 0:49 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-03-11 19:28 [PATCH 0/1] Convert text to ReST list and remove doc build warnings peter 2020-03-11 19:28 ` [PATCH 1/1] Reformat return value descriptions as ReST lists peter 2020-03-11 20:38 ` Russell King - ARM Linux admin 2020-03-11 22:21 ` Peter Lister 2020-03-11 22:25 ` Russell King - ARM Linux admin 2020-03-12 0:49 ` Matthew Wilcox
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).