[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build
From: |
Paolo Bonzini |
Subject: |
Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build |
Date: |
Fri, 1 Nov 2019 00:48:38 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 |
On 29/10/19 19:21, Peter Maydell wrote:
> On Tue, 29 Oct 2019 at 16:22, Paolo Bonzini <address@hidden> 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/address@hidden/
> 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
- [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, Paolo Bonzini, 2019/10/29
- [PATCH 2/6] docs: tweak kernel-doc for QEMU coding standards, Paolo Bonzini, 2019/10/29
- [PATCH 5/6] docs: add memory API reference, Paolo Bonzini, 2019/10/29
- [PATCH 4/6] memory: adjust API documentation to (modified) kerneldoc format, Paolo Bonzini, 2019/10/29
- [PATCH 3/6] docs: disable sphinx warning about missing cross references, Paolo Bonzini, 2019/10/29
- [PATCH 6/6] memory: include MemoryListener documentation and some missing function parameters, Paolo Bonzini, 2019/10/29
- [PATCH 1/6] docs: import Linux kernel-doc script and extension, Paolo Bonzini, 2019/10/29
- Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, no-reply, 2019/10/29
- Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, Peter Maydell, 2019/10/29
- Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build,
Paolo Bonzini <=