* [PATCH 0/1] Format kerneldoc code snippets as literal block
@ 2020-03-11 19:22 peter
2020-03-11 19:22 ` [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks peter
0 siblings, 1 reply; 21+ messages in thread
From: peter @ 2020-03-11 19:22 UTC (permalink / raw)
To: linux-kernel
Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc,
Jonathan Corbet, Peter Lister
From: Peter Lister <peter@bikeshed.quignogs.org.uk>
A minimal patch to better format a couple of kerneldoc code snippets as
literal blocks and so remove kernel doc build warnings.
Peter Lister (1):
Added double colons and blank lines within kerneldoc to format code
snippets as ReST literal blocks.
drivers/base/platform.c | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
--
2.24.1
^ permalink raw reply [flat|nested] 21+ messages in thread* [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks. 2020-03-11 19:22 [PATCH 0/1] Format kerneldoc code snippets as literal block peter @ 2020-03-11 19:22 ` peter 2020-03-11 19:30 ` Jonathan Corbet 0 siblings, 1 reply; 21+ messages in thread From: peter @ 2020-03-11 19:22 UTC (permalink / raw) To: linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> This removes the following warnings from the kernel doc build... ./drivers/base/platform.c:134: WARNING: Unexpected indentation. ./drivers/base/platform.c:213: WARNING: Unexpected indentation. Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> --- drivers/base/platform.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/drivers/base/platform.c b/drivers/base/platform.c index 7fa654f1288b..7fb5cf847253 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -128,7 +128,8 @@ EXPORT_SYMBOL_GPL(devm_platform_ioremap_resource_byname); * request_irq() APIs. This is the same as platform_get_irq(), except that it * does not print an error message if an IRQ can not be obtained. * - * Example: + * Example: :: + * * int irq = platform_get_irq_optional(pdev, 0); * if (irq < 0) * return irq; @@ -207,7 +208,8 @@ EXPORT_SYMBOL_GPL(platform_get_irq_optional); * IRQ fails. Device drivers should check the return value for errors so as to * not pass a negative integer value to the request_irq() APIs. * - * Example: + * Example: :: + * * int irq = platform_get_irq(pdev, 0); * if (irq < 0) * return irq; -- 2.24.1 ^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks. 2020-03-11 19:22 ` [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks peter @ 2020-03-11 19:30 ` Jonathan Corbet 2020-03-26 19:16 ` [PATCH v2 0/1] Compactly make code examples into " peter 0 siblings, 1 reply; 21+ messages in thread From: Jonathan Corbet @ 2020-03-11 19:30 UTC (permalink / raw) To: peter; +Cc: linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Wed, 11 Mar 2020 19:22:56 +0000 peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > This removes the following warnings from the kernel doc build... > ./drivers/base/platform.c:134: WARNING: Unexpected indentation. > ./drivers/base/platform.c:213: WARNING: Unexpected indentation. > > Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> > --- > drivers/base/platform.c | 6 ++++-- > 1 file changed, 4 insertions(+), 2 deletions(-) > > diff --git a/drivers/base/platform.c b/drivers/base/platform.c > index 7fa654f1288b..7fb5cf847253 100644 > --- a/drivers/base/platform.c > +++ b/drivers/base/platform.c > @@ -128,7 +128,8 @@ EXPORT_SYMBOL_GPL(devm_platform_ioremap_resource_byname); > * request_irq() APIs. This is the same as platform_get_irq(), except that it > * does not print an error message if an IRQ can not be obtained. > * > - * Example: > + * Example: :: > + * The change seems good, but you can make it just: * Example:: ...and keep it a bit more readable. Thanks, jon ^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 0/1] Compactly make code examples into literal blocks 2020-03-11 19:30 ` Jonathan Corbet @ 2020-03-26 19:16 ` peter 2020-03-26 19:16 ` [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments peter 0 siblings, 1 reply; 21+ messages in thread From: peter @ 2020-03-26 19:16 UTC (permalink / raw) To: linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> In a previous patch, I fixed a couple of doc build warnings due to a section heading "Example:" which didn't have the intended effect of inserting a heading and literal quoting the following code snippet. I added an explicit double colon to fix warnings and produce nice ReST. Jon suggested that I could have used a minimal form "Example::". Unfortunately not - kernel-doc munges the output so that the formatted output ends up as a stray colon and no literal block. Looking around in the source tree, it seems that parameter definitions can be more complex than the original authors of kernel-doc allowed for. Return values often need lists and examples often should be literal blocks. Many comments in the source are "ASCII formatted" but kernel-doc can make a mess of them and generate doc build warnings along the way. It seems useful to support some terse idioms which serve as compact source annotation and also generate well formed ReST. Here is a first try to let a heading directly introduce a literal block - the "Example::" form for code snippets and an update to platform.c to use it, just as Jon suggested. Peter Lister (1): Provide a compact idiom to add code examples in kerneldoc comments. drivers/base/platform.c | 4 ++-- scripts/kernel-doc | 19 +++++++++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) -- 2.25.1 ^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:16 ` [PATCH v2 0/1] Compactly make code examples into " peter @ 2020-03-26 19:16 ` peter 2020-03-26 19:29 ` Matthew Wilcox 0 siblings, 1 reply; 21+ messages in thread From: peter @ 2020-03-26 19:16 UTC (permalink / raw) To: linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> scripts/kernel-doc - When a double colon follows a section heading (e.g. Example::), write a double colon line to the ReST output to make the following text (e.g. a code snippet) into a literal block. drivers/base/platform.c - Changed Example: headings to Example:: to literalise code snippets as above. This patch also removes two kerneldoc build warnings: ./drivers/base/platform.c:134: WARNING: Unexpected indentation. ./drivers/base/platform.c:213: WARNING: Unexpected indentation. Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> --- drivers/base/platform.c | 4 ++-- scripts/kernel-doc | 19 +++++++++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/drivers/base/platform.c b/drivers/base/platform.c index b5ce7b085795..47f4a9b410b2 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -128,7 +128,7 @@ EXPORT_SYMBOL_GPL(devm_platform_ioremap_resource_byname); * request_irq() APIs. This is the same as platform_get_irq(), except that it * does not print an error message if an IRQ can not be obtained. * - * Example: + * Example:: * int irq = platform_get_irq_optional(pdev, 0); * if (irq < 0) * return irq; @@ -207,7 +207,7 @@ EXPORT_SYMBOL_GPL(platform_get_irq_optional); * IRQ fails. Device drivers should check the return value for errors so as to * not pass a negative integer value to the request_irq() APIs. * - * Example: + * Example:: * int irq = platform_get_irq(pdev, 0); * if (irq < 0) * return irq; diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f2d73f04e71d..b0da150e3fb9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -362,7 +362,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(:?)(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -1952,11 +1952,22 @@ sub process_body($$) { ++$warnings; } } - + # $doc_sect is a regex which searches for section names. + # If it matches: + # $1 is the section name + # $2 is a colon if the section name was followed by a double colon. + # $3 the rest of the content after the colon (or double colon). if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; - $newcontents = $2; - + # If $2 is ':', the section name was followed by a double + # colon, so insert a containing just '::' to make the + # following block into a ReST literal. This idiom is useful + # for an Example section introducing a code snippet. + if ($2 eq ':') { + $newcontents = "::\n" . $3; + } else { + $newcontents = $3; + } # map the supported section names to the canonical names if ($newsection =~ m/^description$/i) { $newsection = $section_default; -- 2.25.1 ^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:16 ` [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments peter @ 2020-03-26 19:29 ` Matthew Wilcox 2020-03-26 19:36 ` Peter Lister 2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter 0 siblings, 2 replies; 21+ messages in thread From: Matthew Wilcox @ 2020-03-26 19:29 UTC (permalink / raw) To: peter Cc: linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet On Thu, Mar 26, 2020 at 07:16:28PM +0000, peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > scripts/kernel-doc - When a double colon follows a section heading > (e.g. Example::), write a double colon line to the ReST output to make > the following text (e.g. a code snippet) into a literal block. I think this is a good idea > - > + # $doc_sect is a regex which searches for section names. > + # If it matches: > + # $1 is the section name > + # $2 is a colon if the section name was followed by a double colon. > + # $3 the rest of the content after the colon (or double colon). I would add an extra 'is' after $3. > if (/$doc_sect/i) { # case insensitive for supported section names > $newsection = $1; > - $newcontents = $2; > - > + # If $2 is ':', the section name was followed by a double > + # colon, so insert a containing just '::' to make the Missing word between 'a' and 'containing'? ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:29 ` Matthew Wilcox @ 2020-03-26 19:36 ` Peter Lister 2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter 1 sibling, 0 replies; 21+ messages in thread From: Peter Lister @ 2020-03-26 19:36 UTC (permalink / raw) To: Matthew Wilcox Cc: linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet Oops. Fair points, well made. v3 on its way... Peter ^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-26 19:29 ` Matthew Wilcox 2020-03-26 19:36 ` Peter Lister @ 2020-03-26 19:51 ` peter 2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter 2020-03-27 11:28 ` [PATCH v3 0/1] Compactly make code examples into literal blocks Jani Nikula 1 sibling, 2 replies; 21+ messages in thread From: peter @ 2020-03-26 19:51 UTC (permalink / raw) To: Matthew Wilcox, linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> [ A couple of typos corrected. Thanks, Matthew ] In a previous patch, I fixed a couple of doc build warnings due to a section heading "Example:" which didn't have the intended effect of inserting a heading and literal quoting the following code snippet. I added an explicit double colon to fix warnings and produce nice ReST. Jon suggested that I could have used a minimal form "Example::". Unfortunately not - kernel-doc munges the output so that the formatted output ends up as a stray colon and no literal block. Looking around in the source tree, it seems that parameter definitions can be more complex than the original authors of kernel-doc allowed for. Return values often need lists and examples often should be literal blocks. Many comments in the source are "ASCII formatted" but kernel-doc can make a mess of them and generate doc build warnings along the way. It seems useful to support some terse idioms which serve as compact source annotation and also generate well formed ReST. Here is a first try to let a heading directly introduce a literal block - the "Example::" form for code snippets and an update to platform.c to use it, just as Jon suggested. Peter Lister (1): A compact idiom to add code examples in kerneldoc comments. drivers/base/platform.c | 4 ++-- scripts/kernel-doc | 19 +++++++++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) -- 2.25.1 ^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter @ 2020-03-26 19:51 ` peter 2020-03-26 19:54 ` Matthew Wilcox 2020-03-27 6:32 ` Greg Kroah-Hartman 2020-03-27 11:28 ` [PATCH v3 0/1] Compactly make code examples into literal blocks Jani Nikula 1 sibling, 2 replies; 21+ messages in thread From: peter @ 2020-03-26 19:51 UTC (permalink / raw) To: Matthew Wilcox, linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister From: Peter Lister <peter@bikeshed.quignogs.org.uk> scripts/kernel-doc - When a double colon follows a section heading (e.g. Example::), write a double colon line to the ReST output to make the following text (e.g. a code snippet) into a literal block. drivers/base/platform.c - Changed Example: headings to Example:: to literalise code snippets as above. This patch also removes two kerneldoc build warnings: ./drivers/base/platform.c:134: WARNING: Unexpected indentation. ./drivers/base/platform.c:213: WARNING: Unexpected indentation. Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> --- drivers/base/platform.c | 4 ++-- scripts/kernel-doc | 19 +++++++++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/drivers/base/platform.c b/drivers/base/platform.c index b5ce7b085795..47f4a9b410b2 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -128,7 +128,7 @@ EXPORT_SYMBOL_GPL(devm_platform_ioremap_resource_byname); * request_irq() APIs. This is the same as platform_get_irq(), except that it * does not print an error message if an IRQ can not be obtained. * - * Example: + * Example:: * int irq = platform_get_irq_optional(pdev, 0); * if (irq < 0) * return irq; @@ -207,7 +207,7 @@ EXPORT_SYMBOL_GPL(platform_get_irq_optional); * IRQ fails. Device drivers should check the return value for errors so as to * not pass a negative integer value to the request_irq() APIs. * - * Example: + * Example:: * int irq = platform_get_irq(pdev, 0); * if (irq < 0) * return irq; diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f2d73f04e71d..732db3dcc402 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -362,7 +362,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(:?)(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -1952,11 +1952,22 @@ sub process_body($$) { ++$warnings; } } - + # $doc_sect is a regex which searches for section names. + # If it matches: + # $1 is the section name + # $2 is a colon if the section name was followed by a double colon. + # $3 is the rest of the content after the colon (or double colon). if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; - $newcontents = $2; - + # If $2 is ':', the section name was followed by a double + # colon, so insert a line containing just '::' to make the + # following block into a ReST literal. This idiom is useful + # for an Example section introducing a code snippet. + if ($2 eq ':') { + $newcontents = "::\n" . $3; + } else { + $newcontents = $3; + } # map the supported section names to the canonical names if ($newsection =~ m/^description$/i) { $newsection = $section_default; -- 2.25.1 ^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter @ 2020-03-26 19:54 ` Matthew Wilcox 2020-03-27 6:32 ` Greg Kroah-Hartman 1 sibling, 0 replies; 21+ messages in thread From: Matthew Wilcox @ 2020-03-26 19:54 UTC (permalink / raw) To: peter Cc: linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet On Thu, Mar 26, 2020 at 07:51:56PM +0000, peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > scripts/kernel-doc - When a double colon follows a section heading > (e.g. Example::), write a double colon line to the ReST output to make > the following text (e.g. a code snippet) into a literal block. > > drivers/base/platform.c - Changed Example: headings to Example:: to > literalise code snippets as above. > > This patch also removes two kerneldoc build warnings: > ./drivers/base/platform.c:134: WARNING: Unexpected indentation. > ./drivers/base/platform.c:213: WARNING: Unexpected indentation. > > Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org> (just to be clear, I'm no python programmer; I like the idea and it looks clear enough to me) ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments. 2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter 2020-03-26 19:54 ` Matthew Wilcox @ 2020-03-27 6:32 ` Greg Kroah-Hartman 1 sibling, 0 replies; 21+ messages in thread From: Greg Kroah-Hartman @ 2020-03-27 6:32 UTC (permalink / raw) To: peter Cc: Matthew Wilcox, linux-kernel, Rafael J. Wysocki, linux-doc, Jonathan Corbet On Thu, Mar 26, 2020 at 07:51:56PM +0000, peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > scripts/kernel-doc - When a double colon follows a section heading > (e.g. Example::), write a double colon line to the ReST output to make > the following text (e.g. a code snippet) into a literal block. > > drivers/base/platform.c - Changed Example: headings to Example:: to > literalise code snippets as above. > > This patch also removes two kerneldoc build warnings: > ./drivers/base/platform.c:134: WARNING: Unexpected indentation. > ./drivers/base/platform.c:213: WARNING: Unexpected indentation. > > Signed-off-by: Peter Lister <peter@bikeshed.quignogs.org.uk> > --- > drivers/base/platform.c | 4 ++-- > scripts/kernel-doc | 19 +++++++++++++++---- > 2 files changed, 17 insertions(+), 6 deletions(-) For the driver/base/platform.c change: Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter 2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter @ 2020-03-27 11:28 ` Jani Nikula 2020-03-27 16:41 ` Jonathan Corbet 1 sibling, 1 reply; 21+ messages in thread From: Jani Nikula @ 2020-03-27 11:28 UTC (permalink / raw) To: peter, Matthew Wilcox, linux-kernel Cc: Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc, Jonathan Corbet, Peter Lister On Thu, 26 Mar 2020, peter@bikeshed.quignogs.org.uk wrote: > From: Peter Lister <peter@bikeshed.quignogs.org.uk> > > [ A couple of typos corrected. Thanks, Matthew ] > > In a previous patch, I fixed a couple of doc build warnings due to a > section heading "Example:" which didn't have the intended effect of > inserting a heading and literal quoting the following code snippet. I > added an explicit double colon to fix warnings and produce nice ReST. > > Jon suggested that I could have used a minimal form "Example::". > Unfortunately not - kernel-doc munges the output so that the formatted > output ends up as a stray colon and no literal block. > > Looking around in the source tree, it seems that parameter definitions > can be more complex than the original authors of kernel-doc allowed > for. Return values often need lists and examples often should be > literal blocks. Many comments in the source are "ASCII formatted" but > kernel-doc can make a mess of them and generate doc build warnings > along the way. > > It seems useful to support some terse idioms which serve as compact > source annotation and also generate well formed ReST. > > Here is a first try to let a heading directly introduce a literal > block - the "Example::" form for code snippets and an update to > platform.c to use it, just as Jon suggested. IMHO the real problem is kernel-doc doing too much preprocessing on the input, preventing us from doing what would be the sensible thing in rst. The more we try to fix the problem by adding more kernel-doc processing, the further we dig ourselves into this hole. If kernel-doc didn't have its own notion of section headers, such as "example:", we wouldn't have this problem to begin with. We could just use the usual rst construct; "example::" followed by an indented block. I'm not going to stand in the way of the patch, but I'm telling you, this is going to get harder, not easier, on this path. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 11:28 ` [PATCH v3 0/1] Compactly make code examples into literal blocks Jani Nikula @ 2020-03-27 16:41 ` Jonathan Corbet 2020-03-27 16:50 ` Matthew Wilcox 2020-03-30 22:29 ` Peter Lister 0 siblings, 2 replies; 21+ messages in thread From: Jonathan Corbet @ 2020-03-27 16:41 UTC (permalink / raw) To: Jani Nikula Cc: peter, Matthew Wilcox, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, 27 Mar 2020 13:28:54 +0200 Jani Nikula <jani.nikula@linux.intel.com> wrote: > IMHO the real problem is kernel-doc doing too much preprocessing on the > input, preventing us from doing what would be the sensible thing in > rst. The more we try to fix the problem by adding more kernel-doc > processing, the further we dig ourselves into this hole. > > If kernel-doc didn't have its own notion of section headers, such as > "example:", we wouldn't have this problem to begin with. We could just > use the usual rst construct; "example::" followed by an indented block. > > I'm not going to stand in the way of the patch, but I'm telling you, > this is going to get harder, not easier, on this path. I agree with you in principle. The problem, of course, is that this is a legacy gift from before the RST days and it will be hard to change. A quick grep shows that the pattern: * Example: appears nearly 100 times in current kernels. It is not inconceivable to make a push to get rid of all of those, turning them into ordinary RST syntax - especially since not all of those are actually kerneldoc comments. The same quick grep says that "returns?:" appears about 10,000 times. *That* will be painful to change, and I can only imagine that some resistance would have to be overcome at some point. So what do folks think we should do? :) I want to ponder on this for a bit. Peter, that may mean that I hold this patch past the 5.7 merge window, which perhaps makes sense at this point anyway, sorry. But I really would like to push things into a direction that moves us away from gnarly perl hacks and toward something more maintainable in the long term. Thanks, jon ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 16:41 ` Jonathan Corbet @ 2020-03-27 16:50 ` Matthew Wilcox 2020-03-27 17:11 ` Jonathan Corbet 2020-03-31 10:50 ` Jani Nikula 2020-03-30 22:29 ` Peter Lister 1 sibling, 2 replies; 21+ messages in thread From: Matthew Wilcox @ 2020-03-27 16:50 UTC (permalink / raw) To: Jonathan Corbet Cc: Jani Nikula, peter, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, Mar 27, 2020 at 10:41:26AM -0600, Jonathan Corbet wrote: > On Fri, 27 Mar 2020 13:28:54 +0200 > Jani Nikula <jani.nikula@linux.intel.com> wrote: > > > IMHO the real problem is kernel-doc doing too much preprocessing on the > > input, preventing us from doing what would be the sensible thing in > > rst. The more we try to fix the problem by adding more kernel-doc > > processing, the further we dig ourselves into this hole. > > > > If kernel-doc didn't have its own notion of section headers, such as > > "example:", we wouldn't have this problem to begin with. We could just > > use the usual rst construct; "example::" followed by an indented block. > > > > I'm not going to stand in the way of the patch, but I'm telling you, > > this is going to get harder, not easier, on this path. > > I agree with you in principle. The problem, of course, is that this is a > legacy gift from before the RST days and it will be hard to change. > > A quick grep shows that the pattern: > > * Example: > > appears nearly 100 times in current kernels. It is not inconceivable to > make a push to get rid of all of those, turning them into ordinary RST > syntax - especially since not all of those are actually kerneldoc > comments. > > The same quick grep says that "returns?:" appears about 10,000 times. > *That* will be painful to change, and I can only imagine that some > resistance would have to be overcome at some point. > > So what do folks think we should do? :) Let me just check I understand Jani's proposal here. You want to change * Return: Number of pages, or negative errno on failure to * Return * ~~~~~~ * Number of pages, or negative errno on failure If so, I oppose such an increase in verbosity and I think most others would too. If not, please let me know what you're actually proposing ;-) ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 16:50 ` Matthew Wilcox @ 2020-03-27 17:11 ` Jonathan Corbet 2020-03-27 17:35 ` Matthew Wilcox 2020-03-31 10:50 ` Jani Nikula 1 sibling, 1 reply; 21+ messages in thread From: Jonathan Corbet @ 2020-03-27 17:11 UTC (permalink / raw) To: Matthew Wilcox Cc: Jani Nikula, peter, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, 27 Mar 2020 09:50:22 -0700 Matthew Wilcox <willy@infradead.org> wrote: > Let me just check I understand Jani's proposal here. You want to change > > * Return: Number of pages, or negative errno on failure > > to > > * Return > * ~~~~~~ > * Number of pages, or negative errno on failure > > If so, I oppose such an increase in verbosity and I think most others > would too. If not, please let me know what you're actually proposing ;-) I told you there would be resistance :) I think a reasonable case can be made for using the same documentation format throughout our docs, rather than inventing something special for kerneldoc comments. So I personally don't think the above is terrible, but as I already noted, I anticipate resistance. An alternative would be to make a little sphinx extension; then it would read more like: .. returns:: Number of pages, except when the moon is full ...which would still probably not be entirely popular. jon ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 17:11 ` Jonathan Corbet @ 2020-03-27 17:35 ` Matthew Wilcox 2020-03-31 11:22 ` Jani Nikula 0 siblings, 1 reply; 21+ messages in thread From: Matthew Wilcox @ 2020-03-27 17:35 UTC (permalink / raw) To: Jonathan Corbet Cc: Jani Nikula, peter, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, Mar 27, 2020 at 11:11:06AM -0600, Jonathan Corbet wrote: > On Fri, 27 Mar 2020 09:50:22 -0700 > Matthew Wilcox <willy@infradead.org> wrote: > > > Let me just check I understand Jani's proposal here. You want to change > > > > * Return: Number of pages, or negative errno on failure > > > > to > > > > * Return > > * ~~~~~~ > > * Number of pages, or negative errno on failure > > > > If so, I oppose such an increase in verbosity and I think most others > > would too. If not, please let me know what you're actually proposing ;-) > > I told you there would be resistance :) Happy to help out! > I think a reasonable case can be made for using the same documentation > format throughout our docs, rather than inventing something special for > kerneldoc comments. So I personally don't think the above is terrible, > but as I already noted, I anticipate resistance. > > An alternative would be to make a little sphinx extension; then it would > read more like: > > .. returns:: Number of pages, except when the moon is full > > ...which would still probably not be entirely popular. I certainly see the value in consistency throughout our documentation. But I don't think it's a given that the documentation of the return value is necessarily its own section. I see kernel-doc as being more about semantic markup and the rst files as being a presentation markup. So I'm fine with Return:: introducing a list or Example:: introducing a code section; these are special purpose keywords. I'm not a fan of using raw rst in kernel-doc. Of course if we can make the kernel-doc and rst languages the same for the same concepts, that's great. ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 17:35 ` Matthew Wilcox @ 2020-03-31 11:22 ` Jani Nikula 0 siblings, 0 replies; 21+ messages in thread From: Jani Nikula @ 2020-03-31 11:22 UTC (permalink / raw) To: Matthew Wilcox, Jonathan Corbet Cc: peter, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, 27 Mar 2020, Matthew Wilcox <willy@infradead.org> wrote: > On Fri, Mar 27, 2020 at 11:11:06AM -0600, Jonathan Corbet wrote: >> On Fri, 27 Mar 2020 09:50:22 -0700 >> Matthew Wilcox <willy@infradead.org> wrote: >> >> > Let me just check I understand Jani's proposal here. You want to change >> > >> > * Return: Number of pages, or negative errno on failure >> > >> > to >> > >> > * Return >> > * ~~~~~~ >> > * Number of pages, or negative errno on failure >> > >> > If so, I oppose such an increase in verbosity and I think most others >> > would too. If not, please let me know what you're actually proposing ;-) >> >> I told you there would be resistance :) > > Happy to help out! > >> I think a reasonable case can be made for using the same documentation >> format throughout our docs, rather than inventing something special for >> kerneldoc comments. So I personally don't think the above is terrible, >> but as I already noted, I anticipate resistance. >> >> An alternative would be to make a little sphinx extension; then it would >> read more like: >> >> .. returns:: Number of pages, except when the moon is full >> >> ...which would still probably not be entirely popular. I don't really think it would need to be a sphinx extension. If I were to do this from scratch, I'd just leave it be any convention that's compatible with rst. Perhaps field lists [1], for both parameters and return values. With that you could do things like: * :Returns: 0 on success. * :Returns: -ENOCOFFEE when out of coffee. * :Returns: Other negative error codes for other errors. or: * :Returns: 0 on success, -ENOCOFFEE when out of coffee, and other negative * error codes for other errors. according to your tastes, and both render nicely. You could actually start using those *now* without changes to kernel-doc or anything. Try it! (Side note, I think it would be nice to preprocess the current @param: stuff into field lists instead of the definition lists that we use now.) > I certainly see the value in consistency throughout our documentation. > But I don't think it's a given that the documentation of the return > value is necessarily its own section. I see kernel-doc as being more > about semantic markup and the rst files as being a presentation markup. > > So I'm fine with Return:: introducing a list or Example:: introducing > a code section; these are special purpose keywords. I'm not a fan of > using raw rst in kernel-doc. Of course if we can make the kernel-doc > and rst languages the same for the same concepts, that's great. IMO, if you want to make a list, you use rst lists. If you want to add a preformatted text block, you use rst preformatted text block. I don't see any reason why those should be tied to certain headings such as "return" or "example". Return does not have to be a list, and example does not have to be a preformatted block. I am also not a fan of *overusing* rst in kernel-doc. But we have it there so that you can use it when you need it, and not have to hack at the godawful kernel-doc the perl script every time. So that you can just point at the widely available documentation on rst for doing everything, instead of telling people to go figure it out from the perl source. BR, Jani. [1] https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 16:50 ` Matthew Wilcox 2020-03-27 17:11 ` Jonathan Corbet @ 2020-03-31 10:50 ` Jani Nikula 1 sibling, 0 replies; 21+ messages in thread From: Jani Nikula @ 2020-03-31 10:50 UTC (permalink / raw) To: Matthew Wilcox, Jonathan Corbet Cc: peter, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Fri, 27 Mar 2020, Matthew Wilcox <willy@infradead.org> wrote: > On Fri, Mar 27, 2020 at 10:41:26AM -0600, Jonathan Corbet wrote: >> On Fri, 27 Mar 2020 13:28:54 +0200 >> Jani Nikula <jani.nikula@linux.intel.com> wrote: >> >> > IMHO the real problem is kernel-doc doing too much preprocessing on the >> > input, preventing us from doing what would be the sensible thing in >> > rst. The more we try to fix the problem by adding more kernel-doc >> > processing, the further we dig ourselves into this hole. >> > >> > If kernel-doc didn't have its own notion of section headers, such as >> > "example:", we wouldn't have this problem to begin with. We could just >> > use the usual rst construct; "example::" followed by an indented block. >> > >> > I'm not going to stand in the way of the patch, but I'm telling you, >> > this is going to get harder, not easier, on this path. >> >> I agree with you in principle. The problem, of course, is that this is a >> legacy gift from before the RST days and it will be hard to change. >> >> A quick grep shows that the pattern: >> >> * Example: >> >> appears nearly 100 times in current kernels. It is not inconceivable to >> make a push to get rid of all of those, turning them into ordinary RST >> syntax - especially since not all of those are actually kerneldoc >> comments. >> >> The same quick grep says that "returns?:" appears about 10,000 times. >> *That* will be painful to change, and I can only imagine that some >> resistance would have to be overcome at some point. >> >> So what do folks think we should do? :) > > Let me just check I understand Jani's proposal here. You want to change > > * Return: Number of pages, or negative errno on failure > > to > > * Return > * ~~~~~~ > * Number of pages, or negative errno on failure > > If so, I oppose such an increase in verbosity and I think most others > would too. If not, please let me know what you're actually proposing ;-) Due to historical reasons, I think kernel-doc must handle a handful of special cases, as a preprocessor converting old conventions to rst. The title line, parameters, returns, and some in-line markup for &struct, etc. I'm not proposing changing "return:", because it's too widespread. I *am* questioning everything else that necessitates adding *more* special casing to handle things that would be easy to do in rst. I think we should be moving in the other direction, fixing things by removing special casing where we can. Case in point, "example:" as a section. Why should we be adding different ways of doing things in the documentation comments and the documentation files? Not having to do that was one of the original goals. Unify stuff to one markup. Make kernel-doc comments in source an extension to the documents under Documentation/. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-27 16:41 ` Jonathan Corbet 2020-03-27 16:50 ` Matthew Wilcox @ 2020-03-30 22:29 ` Peter Lister 2020-03-30 22:32 ` Jonathan Corbet 2020-03-31 11:54 ` Jani Nikula 1 sibling, 2 replies; 21+ messages in thread From: Peter Lister @ 2020-03-30 22:29 UTC (permalink / raw) To: Jonathan Corbet, Jani Nikula Cc: Matthew Wilcox, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On 27/03/2020 16:41, Jonathan Corbet wrote: > On Fri, 27 Mar 2020 13:28:54 +0200 > Jani Nikula <jani.nikula@linux.intel.com> wrote: > >> IMHO the real problem is kernel-doc doing too much preprocessing on the >> input, preventing us from doing what would be the sensible thing in >> rst. The more we try to fix the problem by adding more kernel-doc >> processing, the further we dig ourselves into this hole. >> >> If kernel-doc didn't have its own notion of section headers, such as >> "example:", we wouldn't have this problem to begin with. We could just >> use the usual rst construct; "example::" followed by an indented block. >> >> I'm not going to stand in the way of the patch, but I'm telling you, >> this is going to get harder, not easier, on this path. > I agree with you in principle. The problem, of course, is that this is a > legacy gift from before the RST days and it will be hard to change. > > A quick grep shows that the pattern: > > * Example: > > appears nearly 100 times in current kernels. It is not inconceivable to > make a push to get rid of all of those, turning them into ordinary RST > syntax - especially since not all of those are actually kerneldoc > comments. > > The same quick grep says that "returns?:" appears about 10,000 times. > *That* will be painful to change, and I can only imagine that some > resistance would have to be overcome at some point. > > So what do folks think we should do? :) > > I want to ponder on this for a bit. Peter, that may mean that I hold this > patch past the 5.7 merge window, which perhaps makes sense at this point > anyway, sorry. But I really would like to push things into a direction > that moves us away from gnarly perl hacks and toward something more > maintainable in the long term. I would have been surprised if it had been accepted as is. Matthew and Greg, thanks for reviewing - I have a feeling you might need to do this a few times more. Over the past few days, I too have been pondering, certain thatthis patch, a mini tweak of the existing kernel-doc, is not theright answer.Equally, I'm unconvinced that the "right" answer is a wholesale move to ReST, so where's the happy medium? <alert: long email, tldr: "Finding the happy medium on kerneldoc layout in C source comments"> A week or two back, I tried to fix doc build "indentation" warnings due to return value listsin sfb-bus.c. Russell King didn't like my patch saying "I think it's more important that the documentation interferes to a minimal degree with the code in the file".[ Mauro's patch to sfb-bus.c is now in linux-next. He fixed the problem with a bullet list - thriftier with the line breaks andthe official fix in the kerneldoc notes - but I'll argue that a simple list or definition list might be more appropriate. ] Russell and Matthew argue that the primary purpose of source annotation is to aid developers and that any significant detraction (verbosity, whitespace) is not excused by prettier docs. FWIW, my background is sysadmin (much perl) and system/kernel programming (mostly C) and I agree with them. Jani, if you see risks of complexity and maintenance problems, then so do I. But the point of kernel-doc is surely to be a specific semantic markup which works for developers and maintainers and allows doc authors access to their annotation. The format clearly needs thought,perl is less fashionable than it was and kernel-doc - er - needs work, but I don't see the *idea* as inherently broken. I suggest that there would be good developer buy-in to searchable pretty docs if a few compact idioms reliably did The Right Thing and didn't spit out doc build warnings. The build warnings I currently observe do not tell me "the author got it wrong", but rather "kernel-doc didn't understand the author's intention". Consider this excerpt from the kerneldoc comment for bitmap_cut(), recently added to lib/bitmap.c. (NB - this is an example in the description section - the parameters, including src, have already been described). * In pictures, example for a big-endian 32-bit architecture: * * @src: * 31 63 * | | * 10000000 11000001 11110010 00010101 10000000 11000001 01110010 00010101 * | | | | * 16 14 0 32 * This fails because 1) the diagram isn't made literal (and so generates a indentation build warning) and 2) "@src:" is interpreted as an extra definition of src which scrunges the first one. I find it hard to assert that the author's intentions were wrong; it's the kind of good annotation we should hope for in a newly added function. If "* @src:" gained an double colon and we guaranteed that, after a description section header, references to a parameter didn't overwrite the original definition, this would work fine. My instinct is to fix doc build issues with minimal changes: not actual ReST, but clear idioms reliably generating good ReST. This should be accompanied by tests for developers and reviewers so that we can have a fair stab at getting it right first time and (of course) documentation. Could I ask anyone who disagrees to suggest their preferred way to lay out the comment for bitmap_cut()? One head-on approachis to literalise *all* kerneldoc comments for functions and structures. The kerneldoc keywords then serve only to generate links; the ReST output is minimal but guaranteed validand warning free. Would any readers of API docs be inconvenienced? The target readership are presumably programmers, and the searchability of the sphinx RTD is more useful to me than the formatting. All the best, Peter ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-30 22:29 ` Peter Lister @ 2020-03-30 22:32 ` Jonathan Corbet 2020-03-31 11:54 ` Jani Nikula 1 sibling, 0 replies; 21+ messages in thread From: Jonathan Corbet @ 2020-03-30 22:32 UTC (permalink / raw) To: Peter Lister Cc: Jani Nikula, Matthew Wilcox, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Mon, 30 Mar 2020 23:29:24 +0100 Peter Lister <peter@bikeshed.quignogs.org.uk> wrote: One quick thing caught my eye... > One head-on approachis to literalise *all* kerneldoc comments for > functions and structures. The kerneldoc keywords then serve only to > generate links; the ReST output is minimal but guaranteed validand > warning free. Would any readers of API docs be inconvenienced? The > target readership are presumably programmers, and the searchability of > the sphinx RTD is more useful to me than the formatting. The ability to put formatting directive into kerneldoc comments was one of the driving forces that pushed the RST switch in the first place. There are subsystems that make use of this capability and would not be pleased to see it go away. jon ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v3 0/1] Compactly make code examples into literal blocks 2020-03-30 22:29 ` Peter Lister 2020-03-30 22:32 ` Jonathan Corbet @ 2020-03-31 11:54 ` Jani Nikula 1 sibling, 0 replies; 21+ messages in thread From: Jani Nikula @ 2020-03-31 11:54 UTC (permalink / raw) To: Peter Lister, Jonathan Corbet Cc: Matthew Wilcox, linux-kernel, Greg Kroah-Hartman, Rafael J. Wysocki, linux-doc On Mon, 30 Mar 2020, Peter Lister <peter@bikeshed.quignogs.org.uk> wrote: > On 27/03/2020 16:41, Jonathan Corbet wrote: > >> On Fri, 27 Mar 2020 13:28:54 +0200 >> Jani Nikula <jani.nikula@linux.intel.com> wrote: >> >>> IMHO the real problem is kernel-doc doing too much preprocessing on the >>> input, preventing us from doing what would be the sensible thing in >>> rst. The more we try to fix the problem by adding more kernel-doc >>> processing, the further we dig ourselves into this hole. >>> >>> If kernel-doc didn't have its own notion of section headers, such as >>> "example:", we wouldn't have this problem to begin with. We could just >>> use the usual rst construct; "example::" followed by an indented block. >>> >>> I'm not going to stand in the way of the patch, but I'm telling you, >>> this is going to get harder, not easier, on this path. >> I agree with you in principle. The problem, of course, is that this is a >> legacy gift from before the RST days and it will be hard to change. >> >> A quick grep shows that the pattern: >> >> * Example: >> >> appears nearly 100 times in current kernels. It is not inconceivable to >> make a push to get rid of all of those, turning them into ordinary RST >> syntax - especially since not all of those are actually kerneldoc >> comments. >> >> The same quick grep says that "returns?:" appears about 10,000 times. >> *That* will be painful to change, and I can only imagine that some >> resistance would have to be overcome at some point. >> >> So what do folks think we should do? :) >> >> I want to ponder on this for a bit. Peter, that may mean that I hold this >> patch past the 5.7 merge window, which perhaps makes sense at this point >> anyway, sorry. But I really would like to push things into a direction >> that moves us away from gnarly perl hacks and toward something more >> maintainable in the long term. > > I would have been surprised if it had been accepted as is. > > Matthew and Greg, thanks for reviewing - I have a feeling you might need > to do this a few times more. > > Over the past few days, I too have been pondering, certain thatthis > patch, a mini tweak of the existing kernel-doc, is not theright > answer.Equally, I'm unconvinced that the "right" answer is a wholesale > move to ReST, so where's the happy medium? > > <alert: long email, tldr: "Finding the happy medium on kerneldoc layout > in C source comments"> > > A week or two back, I tried to fix doc build "indentation" warnings due > to return value listsin sfb-bus.c. Russell King didn't like my patch > saying "I think it's more important that the documentation interferes to > a minimal degree with the code in the file".[ Mauro's patch to sfb-bus.c > is now in linux-next. He fixed the problem with a bullet list - > thriftier with the line breaks andthe official fix in the kerneldoc > notes - but I'll argue that a simple list or definition list might be > more appropriate. ] > > Russell and Matthew argue that the primary purpose of source annotation > is to aid developers and that any significant detraction (verbosity, > whitespace) is not excused by prettier docs. FWIW, my background is > sysadmin (much perl) and system/kernel programming (mostly C) and I > agree with them. > > Jani, if you see risks of complexity and maintenance problems, then so > do I. But the point of kernel-doc is surely to be a specific semantic > markup which works for developers and maintainers and allows doc authors > access to their annotation. The format clearly needs thought,perl is > less fashionable than it was and kernel-doc - er - needs work, but I > don't see the *idea* as inherently broken. I suggest that there would be > good developer buy-in to searchable pretty docs if a few compact idioms > reliably did The Right Thing and didn't spit out doc build warnings. Historically the kernel documentation build was a Rube Goldberg machine, and if you were lucky, you reached the end. There were failure points all over the place. There were "impedance mismatches" in the inputs and outputs at various stages. There were *insane* escaping issues to get some text passed through as intended. At the high level, we've reduced that to *two*, Sphinx and kernel-doc the perl script, we've made kernel-doc emit rst instead of xml/html, and we even run the script from within a Sphinx extension to get the error reporting and dependency management right. Being able to throw away a lot of conversion and interpretation from kernel-doc was a goal, passing through the kernel-doc comments unchanged as much as possible was a feature. This was really the key to making it possible to document the kernel with Sphinx to begin with. I think it's a mistake to add anything to kernel-doc that isn't trying to streamline that process even more. Minimize what kernel-doc does as much as possible (but not more). The moment you start adding "a few compact idioms", you start introducing more ways to trip over the mismatch between kernel-doc syntax and rst. And you end up trying to figure out ways to escape stuff in one or the other. BR, Jani. PS. The kernel was always going to be held back by insane amounts of existing kernel-doc comments, as well as aversion to adding build dependencies. My vision of what a minimalistic Sphinx based C code documentation system free of those ties might look like is Hawkmoth [1]. [1] https://github.com/jnikula/hawkmoth > > The build warnings I currently observe do not tell me "the author got it > wrong", but rather "kernel-doc didn't understand the author's intention". > > Consider this excerpt from the kerneldoc comment for bitmap_cut(), > recently added to lib/bitmap.c. (NB - this is an example in the > description section - the parameters, including src, have already been > described). > > * In pictures, example for a big-endian 32-bit architecture: > * > * @src: > * 31 63 > * | | > * 10000000 11000001 11110010 00010101 10000000 11000001 01110010 00010101 > * | | | | > * 16 14 0 32 > * > > This fails because 1) the diagram isn't made literal (and so generates a > indentation build warning) and 2) "@src:" is interpreted as an extra > definition of src which scrunges the first one. I find it hard to assert > that the author's intentions were wrong; it's the kind of good > annotation we should hope for in a newly added function. If "* @src:" > gained an double colon and we guaranteed that, after a description > section header, references to a parameter didn't overwrite the original > definition, this would work fine. > > My instinct is to fix doc build issues with minimal changes: not actual > ReST, but clear idioms reliably generating good ReST. This should be > accompanied by tests for developers and reviewers so that we can have a > fair stab at getting it right first time and (of course) documentation. > > Could I ask anyone who disagrees to suggest their preferred way to lay > out the comment for bitmap_cut()? > > One head-on approachis to literalise *all* kerneldoc comments for > functions and structures. The kerneldoc keywords then serve only to > generate links; the ReST output is minimal but guaranteed validand > warning free. Would any readers of API docs be inconvenienced? The > target readership are presumably programmers, and the searchability of > the sphinx RTD is more useful to me than the formatting. > > All the best, > Peter -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2020-03-31 11:54 UTC | newest] Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-03-11 19:22 [PATCH 0/1] Format kerneldoc code snippets as literal block peter 2020-03-11 19:22 ` [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks peter 2020-03-11 19:30 ` Jonathan Corbet 2020-03-26 19:16 ` [PATCH v2 0/1] Compactly make code examples into " peter 2020-03-26 19:16 ` [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments peter 2020-03-26 19:29 ` Matthew Wilcox 2020-03-26 19:36 ` Peter Lister 2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter 2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter 2020-03-26 19:54 ` Matthew Wilcox 2020-03-27 6:32 ` Greg Kroah-Hartman 2020-03-27 11:28 ` [PATCH v3 0/1] Compactly make code examples into literal blocks Jani Nikula 2020-03-27 16:41 ` Jonathan Corbet 2020-03-27 16:50 ` Matthew Wilcox 2020-03-27 17:11 ` Jonathan Corbet 2020-03-27 17:35 ` Matthew Wilcox 2020-03-31 11:22 ` Jani Nikula 2020-03-31 10:50 ` Jani Nikula 2020-03-30 22:29 ` Peter Lister 2020-03-30 22:32 ` Jonathan Corbet 2020-03-31 11:54 ` Jani Nikula
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).