On Fri 2021-12-10 10:24:58, David Vernet wrote: > Petr Mladek <pmladek@xxxxxxxx> 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
