Re: [PATCH] Documentation: livepatch: Add kernel-doc link to klp_enable_patch

[Petr Mladek <pmladek@suse.com>]

On Fri 2021-12-10 10:24:58, David Vernet wrote:
> Petr Mladek <pmladek@suse.com> wrote on Fri [2021-Dec-10 10:25:05 +0100]:
> > 
> > Honestly, I do not like this. It might be acceptable when it converts
> > klp_enable_patch() into a link pointing to another page describing the API.
> > 
> > But this patch causes the entire documentation of klp_enable_patch()
> > inserted into livepatch.html. It does not fit there and breaks
> > the text flow.
> 
> Thank you for taking a look at the patch, Petr.
> 
> I'm happy to revise the patch to instead add a new `api.rst` file that
> contains the `kernel-doc` directive, which would cause `klp_enable_patch()`
> in `livepatch.rst` to automatically link to the separate page as you
> suggested.
> 
> Just to check though -- I see that `shadow-vars.rst` and `system-state.rst`
> have their own "API" sections.

Good point. Well, even these file do not point to the documentation
generated from the sources.


> Is it preferable to add such a section directly to `livepatch.rst`,
> rather than creating a separate file?

Good question. I am not expert on writing documentation and I can't
find any good example of API documentation at
https://www.kernel.org/doc/html/latest/index.html

One reason might be that most of the documentation was written as plain text
in the past. And many people still read it in the original .rst form.

Another problem is that livepatch documentation is a mix of several
independent pieces written by different authors. It would deserve
a lot of work:

    + Connect the pieces
    + Add missing information
    + Make the style and structure consistent


Anyway, I think that the documentation generated from the sources
is useful. But it is hard to integrate it into .rst file that should
be useful even in the .rst format.

From this POV, I suggest to create Documentation/livepatch/API.rst
and add there the documentation generated from the sources. I mean
something like:

    Documentation/core-api/kernel-api.rst

that results into

https://www.kernel.org/doc/html/latest/core-api/kernel-api.html


The livepatch/API.rst might include documentation from

    include/linux/livepatch.h
    kernel/livepatch/code.c
    kernel/livepatch/shadow.c
    kernel/livepatch/state.c


But let's wait if there are other opinions from another livepatch
developers.

Best Regards,
Petr