[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues
From: |
Peter Maydell |
Subject: |
[Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues |
Date: |
Tue, 21 May 2019 13:25:16 +0100 |
If you try to use kerneldoc to extract the doc comments from
memory.h and run sphinx on it, it generates some warnings:
* various functions are missing a parameter in the docs
* some 'unexpected indentation' warnings where a list
isn't marked up with the leading/trailing blank lines and
bullet markers that rST expects
These aren't the only issues, but they are the only ones
that are actually warned about (as opposed to generating
misformatted output).
Signed-off-by: Peter Maydell <address@hidden>
---
include/exec/memory.h | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/include/exec/memory.h b/include/exec/memory.h
index 9144a47f571..8447a16ded1 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -907,6 +907,7 @@ void memory_region_init_rom(MemoryRegion *mr,
* @mr: the #MemoryRegion to be initialized.
* @owner: the object that tracks the region's reference count
* @ops: callbacks for write access handling (must not be NULL).
+ * @opaque: passed to the read and write callbacks of the @ops structure.
* @name: Region name, becomes part of RAMBlock name used in migration stream
* must be unique within any device
* @size: size of the region.
@@ -995,7 +996,7 @@ static inline IOMMUMemoryRegion
*memory_region_get_iommu(MemoryRegion *mr)
* Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
* otherwise NULL. This is fast path avoiding QOM checking, use with caution.
*
- * @mr: the memory region being queried
+ * @iommu_mr: the memory region being queried
*/
static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck(
IOMMUMemoryRegion *iommu_mr)
@@ -1558,6 +1559,7 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr,
/**
* memory_region_get_ram_addr: Get the ram address associated with a memory
* region
+ * @mr: the memory region to get the ram address for
*/
ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
@@ -1650,6 +1652,7 @@ bool memory_region_is_mapped(MemoryRegion *mr);
*
* Returns a #MemoryRegionSection that describes a contiguous overlap.
* It will have the following characteristics:
+ *
* address@hidden = 0 iff no overlap was found
* address@hidden is non-%NULL iff an overlap was found
*
@@ -1657,11 +1660,12 @@ bool memory_region_is_mapped(MemoryRegion *mr);
* relative to the returned region (in the address@hidden field), not to the
* @mr argument.
*
- * Similarly, the address@hidden is relative to the
+ * Similarly, the @.offset_within_address_space is relative to the
* address space that contains both regions, the passed and the
* returned one. However, in the special case where the @mr argument
* has no container (and thus is the root of the address space), the
* following will hold:
+ *
* address@hidden >= @addr
* address@hidden + address@hidden <= @addr + @size
*
@@ -2107,6 +2111,7 @@ static inline bool memory_access_is_direct(MemoryRegion
*mr, bool is_write)
* @addr: address within that address space
* @attrs: memory transaction attributes
* @buf: buffer with the data transferred
+ * @len: length of the buffer
*/
static inline __attribute__((__always_inline__))
MemTxResult address_space_read(AddressSpace *as, hwaddr addr,
--
2.20.1
- [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module from Linux, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues,
Peter Maydell <=
- [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs, Peter Maydell, 2019/05/21
- [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux, Peter Maydell, 2019/05/21
- Re: [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup, Peter Maydell, 2019/05/21
- Re: [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup, no-reply, 2019/05/21