On 29/10/19 19:21, Peter Maydell wrote:
> On Tue, 29 Oct 2019 at 16:22, Paolo Bonzini <[email protected]> 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/[email protected]/
> 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
