Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build

[Paolo Bonzini <pbonzini@redhat.com>]

On 29/10/19 19:21, Peter Maydell wrote:
> On Tue, 29 Oct 2019 at 16:22, Paolo Bonzini <pbonzini@redhat.com> wrote:
>>
>> Hello,
>>
>> this is an attempt at including kernel-doc, with small tweaks (see patch
>> 2) to support QEMU's doc comment format, in the Sphinx documentation pipeline.
>>
>> The ugly part is patch 3, which disables Sphinx's "nitpicking" (warn on
>> invalid cross-reference) mode.  It would probably be possible to use
>> the nitpick_ignore configuration entry instead.
>>
>> Paolo
>>
>> Paolo Bonzini (6):
>>   docs: import Linux kernel-doc script and extension
>>   docs: tweak kernel-doc for QEMU coding standards
>>   docs: disable sphinx warning about missing cross references
>>   memory: adjust API documentation to (modified) kerneldoc format
>>   docs: add memory API reference
>>   memory: include MemoryListener documentation and some missing function
>>     parameters
> 
> Could you briefly describe the differences between this patchset
> and the RFC I sent a while back:
> https://patchew.org/QEMU/20190521122519.12573-1-peter.maydell@linaro.org/
> please?

Thanks for the pointer, I didn't remember it; my series is not based on
your work.  The main difference is in patch 2 ("docs: tweak kernel-doc
for QEMU coding standards"), which tweaks kernel-doc to recognize camel
case types and QEMU's usage of "#" to indicate types (inspired by GTKDoc
and different from the "&" sigil used in the kernel sources).

As a result of this, the adjustments to be made to header files are much
smaller.  In particular there are no hunks such as


 /**
- * MemoryListener: callbacks structure for updates to the physical
memory map
+ * struct MemoryListener: callbacks structure for updates to the
physical memory map
  *

The other difference is that this is based on newer kernel sources,
therefore I had to import the additional file docs/sphinx/kernellog.py.
 On the other hand, I forgot to commit docs/sphinx/kerneldoc.py...

If we agree that nitpicking mode is unmaintainable, I can merge your
work with mine and repost.

Thanks,

Paolo