Re: Kernel docs: muddying the waters a bit

[Jani Nikula]

On Wed, 04 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>> What do you mean by ".tmpl workflow"?
>
> Sorry for bad naming, I addressed the DOCPROC build process which builds
> the .xml files from .tmpl files ...

Yeah, I know more about this part than I care. I was just wondering what
you refer to with that in the sphinx context.

> In reST the directive might look like:
>
> <reST-SNIP> -----
> Device Instance and Driver Handling
> ===================================
>
> .. kernel-doc::  drivers/gpu/drm/drm_drv.c
>    :doc:      driver instance overview
>    :exported:
>
> <reST-SNAP> -----

Yes, I think something like this, parsed by sphinx directly (via some
extension perhaps), should be the end goal. I am not sure if it should
be the immediate first goal though or whether we should reuse the
existing docproc for now.

> Right, but you forgot, that the current markup in the source code comments
> is based on the  kernel-doc-nano-HOWTO and I guess no one will migrate all
> these source code comments to reST markup ;-)
>
> So there is a need to differentiate between *vintage* kernel-doc markup 
> and reST markup.
>
> My suggestion is to add a tag to the comments, here a short example
> what this might look like.
>
> <vintage-comment-SNIP> --------------
> /**
>  * drm_minor_release - Release DRM minor
>  * @minor: Pointer to DRM minor object
>  *
>  * Release a minor that was previously acquired via drm_minor_acquire().
>  */
> <vintage-comment-SNAP> --------------
>
> in short: the vintage style does not need any change and 
> comments with reST markup has a tag ":reST:" in the first 
> line(s) ...
>
> <reST-comment-SNIP> --------------
> /**
>  * :reST:
>  *
>  * .. c:function:: void drm_minor_release(struct drm_minor *minor)
>  *
>  *    Release DRM minor
>  *
>  *    :param struct drm_minor \*minor: Pointer to DRM minor object
>  *
>  */
> <reST-comment-SNAP> --------------
>
> Comments with the ":reST:" tag could be exported and pass-through
> to sphinx.

Disagreed on most of the above.

Maybe I was unclear in my previous mail, and I've probably worked on
this so much previously that I thought it was clear how we should handle
lightweight markup in kernel-doc comments.

Kernel-doc the tool should continue to parse kernel-doc comments at the
high level like they currently are, according to the kernel-doc
howto. The first heading line, the parameter/member lines with @param:,
and references within the text with @param, function(), &struct
structures, etc. For those, kernel-doc should produce appropriate rst
elements.

Beyond that, kernel-doc should *not* try to make guesses about the
formatting of the documentation comments. It should just pass the rest
of the formatting through. If the ad-hoc lists etc. in the current
comments don't turn into proper rst lists, then so be it. If it bugs
people, the comments will gradually be converted to proper rst. The
worst we could do is promote a sloppy style that kernel-doc fixes for
you, possibly "fixing" things you'd want to pass through to sphinx.

What you have in <reST-comment-SNAP> example above will not fly. The
documentation comment style must remain as is defined in the kernel-doc
how, i.e. <vintage-comment-SNAP> example. It is imperative that the
kernel-doc comments remain as readable as they currently are in the
source code.

>> Specifically, do not attempt to detect and
>> parse elements like lists in kernel-doc.
>
> If your markup in the comments is plain reST, no need to parse, but there
> are markups in the (vintage) comments which made use of individual 
> text-markups, e.g. the markup of lists or ASCII-art. 
>
> This individual text-markups has not been converted/rendered in the docbook
> output, but I wanted to convert this individuals to reST, to render them in
> Sphinx.
>
> E.g. compare the member & description section of struct drm-display-mode ...
>
> DocBook: 
>
>   * https://www.kernel.org/doc/htmldocs/gpu/API-struct-drm-display-mode.html
>
> kernel-doc reST with the additional reformat_block_rst function:
>
>   * http://return42.github.io/sphkerneldoc/linux_src_doc/include/drm/drm_modes_h.html#struct-drm-display-mode

Overall I think we should promote fixing those in the kernel-doc
comments. Trying to guesswork in kernel-doc tool will leave the source
littered with bad examples that get proliferated all around. Instead of
gradually fixing things, we'll end up gradually messing things up even
more.

For those specific examples, IIRC the last time I played with that,
simply leaving the prefix whitespace in place went a long way (just eat
" * " from the lines). The asciiart just worked.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center