Help required - kernel-doc, code block and backslash

Help required - kernel-doc, code block and backslash

[Anna-Maria Behnsen]

Hi,

I'll try to integrate some documentation which is already written in
code comments into the kernel documentation.

There I face the problem with a backslash at the end of a line in a
'code block' and this ends up in removing the newline.

So I have this comment in code and I simply want to use the kernel-doc
'doc' option to integrate it into documentation:

/**
 * DOC: example
 *
 * This should illustrate a hierarchy as a code block::
 *
 *                    Top Level
 *                /               \
 *        Parent A                 Parent B
 *       /        \               /        \
 *  Child A      Child B       Child C   Child D
 *
 */

And the code block looks like this after using the make target
'htmldocs':

             Top Level
         /                *        parent A                 parent B
/        \               /         *  Child A      Child B       Child C   Child D


I wonder, if there is something broken (as the * of the c comment is in
there again)?

Another question: Is there an linux-doc irc channel to ask simple
questions?

Thanks,
	Anna-Maria

Re: Help required - kernel-doc, code block and backslash

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

> Hi,
>
> I'll try to integrate some documentation which is already written in
> code comments into the kernel documentation.
>
> There I face the problem with a backslash at the end of a line in a
> 'code block' and this ends up in removing the newline.

Yes, kernel-doc does that...looking at the history, that behavior was
added in 2012 (commit 65478428443) because otherwise multi-line macros
are not handled properly.

Fixing this properly is not going to be all that easy; the code reading
the source file is well before any sort of parsing, so it has no idea of
whether it's in a comment or not.

A really ugly workaround... put something relatively inconspicuous, like
"     .", after the backslash, and at least your formatting won't be
mangled.

> Another question: Is there an linux-doc irc channel to ask simple
> questions?

I don't really do IRC, just don't have the spare attention span for it.
Feel free to email me anytime though.

jon

Re: Help required - kernel-doc, code block and backslash

[Matthew Wilcox]

On Mon, Jan 15, 2024 at 12:38:38PM -0700, Jonathan Corbet wrote:
> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
> 
> > Hi,
> >
> > I'll try to integrate some documentation which is already written in
> > code comments into the kernel documentation.
> >
> > There I face the problem with a backslash at the end of a line in a
> > 'code block' and this ends up in removing the newline.
> 
> Yes, kernel-doc does that...looking at the history, that behavior was
> added in 2012 (commit 65478428443) because otherwise multi-line macros
> are not handled properly.
> 
> Fixing this properly is not going to be all that easy; the code reading
> the source file is well before any sort of parsing, so it has no idea of
> whether it's in a comment or not.
> 
> A really ugly workaround... put something relatively inconspicuous, like
> "     .", after the backslash, and at least your formatting won't be
> mangled.

Well ... if we're into "ugly workaround" territory, we could use '^ *'
as a marker for "we're in a comment, ignore the backslash".  My skills
in this area are terrible, so would something like this work?

while (!/^ \*/ && s/\\\s*$//) {

I would try it myself, but Something Changed, and even without it,
I've just started getting:

Sphinx parallel build error:
AssertionError

when I run make htmldocs.

Re: Help required - kernel-doc, code block and backslash

[Vegard Nossum]

On 15/01/2024 20:38, Jonathan Corbet wrote:
> A really ugly workaround... put something relatively inconspicuous, like
> "     .", after the backslash, and at least your formatting won't be
> mangled.

Something like this should also work, not sure if it would be considered
acceptable though:

  * This should illustrate a hierarchy as a code block::
  *
  *  +----------------------------------------------+
  *  |                   Top Level                  |
  *  |               /               \              |
  *  |       Parent A                 Parent B      |
  *  |      /         \              /        \     |
  *  | Child A      Child B       Child C   Child D |
  *  +----------------------------------------------+

(note the double space after *, which counts as an indentation)


Vegard

Re: Help required - kernel-doc, code block and backslash

[Anna-Maria Behnsen]

Matthew Wilcox <willy@infradead.org> writes:

> On Mon, Jan 15, 2024 at 12:38:38PM -0700, Jonathan Corbet wrote:
>> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>> 
>> > Hi,
>> >
>> > I'll try to integrate some documentation which is already written in
>> > code comments into the kernel documentation.
>> >
>> > There I face the problem with a backslash at the end of a line in a
>> > 'code block' and this ends up in removing the newline.
>> 
>> Yes, kernel-doc does that...looking at the history, that behavior was
>> added in 2012 (commit 65478428443) because otherwise multi-line macros
>> are not handled properly.
>> 
>> Fixing this properly is not going to be all that easy; the code reading
>> the source file is well before any sort of parsing, so it has no idea of
>> whether it's in a comment or not.
>> 
>> A really ugly workaround... put something relatively inconspicuous, like
>> "     .", after the backslash, and at least your formatting won't be
>> mangled.
>
> Well ... if we're into "ugly workaround" territory, we could use '^ *'
> as a marker for "we're in a comment, ignore the backslash".  My skills
> in this area are terrible, so would something like this work?
>
> while (!/^ \*/ && s/\\\s*$//) {

Thanks! A smoke test looks good (except of required clenaup of some
comments which use backslashes). But I'll have a deeper look at it to
verify it completely.

Thanks,

	Anna-Maria

Re: Help required - kernel-doc, code block and backslash

[Anna-Maria Behnsen]

Hi Jon,

Jonathan Corbet <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

>> Another question: Is there an linux-doc irc channel to ask simple
>> questions?
>
> I don't really do IRC, just don't have the spare attention span for it.
> Feel free to email me anytime though.

Thank you very much! So I directly use this to ask another questions :)

When using the kernel-doc 'identifiers' option, is there a way to use
wildcards or a easy way to enable wildcards? Something like this:

.. kernel-doc:: include/linux/jiffies.h
   :identifiers: time_*

Thanks,

	Anna-Maria

Re: Help required - kernel-doc, code block and backslash

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

> Hi Jon,
>
> Jonathan Corbet <corbet@lwn.net> writes:
>
>> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>
>>> Another question: Is there an linux-doc irc channel to ask simple
>>> questions?
>>
>> I don't really do IRC, just don't have the spare attention span for it.
>> Feel free to email me anytime though.
>
> Thank you very much! So I directly use this to ask another questions :)
>
> When using the kernel-doc 'identifiers' option, is there a way to use
> wildcards or a easy way to enable wildcards? Something like this:
>
> .. kernel-doc:: include/linux/jiffies.h
>    :identifiers: time_*

Not currently.  That would be useful, though, and easy enough to add.
We just need to decide whether we want filename-glob matching, or proper
regexes...

Thanks,

jon

Re: Help required - kernel-doc, code block and backslash

[Anna-Maria Behnsen]

Jonathan Corbet <corbet@lwn.net> writes:
> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

[...]

>> When using the kernel-doc 'identifiers' option, is there a way to use
>> wildcards or a easy way to enable wildcards? Something like this:
>>
>> .. kernel-doc:: include/linux/jiffies.h
>>    :identifiers: time_*
>
> Not currently.  That would be useful, though, and easy enough to add.
> We just need to decide whether we want filename-glob matching, or proper
> regexes...
>

Maybe I'm on the wrong track (definitely possible as I am a
scripting/tooling amateur), but I thought identifiers option takes a
list of functions or types and not filenames?

In case the filename-glob matching is this what I would call wildcard
matching, then I would propose to enable this for the existing
option. In case regexes are required as well, maybe another option like
'[no-]identifiers-regex' could be introduced.

Thanks,

	Anna-Maria

Re: Help required - kernel-doc, code block and backslash

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

> Maybe I'm on the wrong track (definitely possible as I am a
> scripting/tooling amateur), but I thought identifiers option takes a
> list of functions or types and not filenames?

No, you're right.  I was talking about the type of matching desired.

> In case the filename-glob matching is this what I would call wildcard
> matching, then I would propose to enable this for the existing
> option. In case regexes are required as well, maybe another option like
> '[no-]identifiers-regex' could be introduced.

Given that we've gotten by with no matching support until now, I don't
think that we need to add two types :)  Basic globbing it is, though I
can't promise to get it done right away.  That will have to be done on
the Perl side, and I get really slow in that world...

Thanks,

jon