LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
* [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	[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).