diff mbox series

[RFC,07/10] memory.h: Fix kerneldoc syntax issues

Message ID 20190521122519.12573-8-peter.maydell@linaro.org
State Superseded
Headers show
Series Add kernel-doc support to our Sphinx setup | expand

Commit Message

Peter Maydell May 21, 2019, 12:25 p.m. UTC 
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 <peter.maydell@linaro.org>

---
 include/exec/memory.h | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

-- 
2.20.1
diff mbox series

Patch

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:
+ *
  *    .@size = 0 iff no overlap was found
  *    .@mr 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 .@mr field), not to the
  * @mr argument.
  *
- * Similarly, the .@offset_within_address_space 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:
+ *
  *    .@offset_within_address_space >= @addr
  *    .@offset_within_address_space + .@size <= @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,