Help required - kernel-doc, code block and backslash

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

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.

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

jon

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.

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

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

Hi Jon,

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

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

[...]

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

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

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