[RFC PATCH 6/6] docs/devel: add some clarifying text for aliases

From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: qemu-arm@nongnu.org, "Alex Bennée" <alex.bennee@linaro.org>
Subject: [RFC PATCH  6/6] docs/devel: add some clarifying text for aliases
Date: Mon, 10 Jan 2022 17:51:04 +0000	[thread overview]
Message-ID: <20220110175104.2908956-7-alex.bennee@linaro.org> (raw)
In-Reply-To: <20220110175104.2908956-1-alex.bennee@linaro.org>

We do mention the limitation of single parenthood for
memory_region_add_subregion but lets also make it clear how aliases
help solve that conundrum.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/devel/memory.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst
index 5dc8a12682..69c5e3f914 100644
--- a/docs/devel/memory.rst
+++ b/docs/devel/memory.rst
@@ -67,11 +67,15 @@ MemoryRegion):
 
   You initialize a pure container with memory_region_init().
 
-- alias: a subsection of another region.  Aliases allow a region to be
-  split apart into discontiguous regions.  Examples of uses are memory banks
-  used when the guest address space is smaller than the amount of RAM
-  addressed, or a memory controller that splits main memory to expose a "PCI
-  hole".  Aliases may point to any type of region, including other aliases,
+- alias: a subsection of another region. Aliases allow a region to be
+  split apart into discontiguous regions. Examples of uses are memory
+  banks used when the guest address space is smaller than the amount
+  of RAM addressed, or a memory controller that splits main memory to
+  expose a "PCI hole". You can also create aliases to avoid trying to
+  add the original region to multiple parents via
+  `memory_region_add_subregion`.
+
+  Aliases may point to any type of region, including other aliases,
   but an alias may not point back to itself, directly or indirectly.
   You initialize these with memory_region_init_alias().
 
-- 
2.30.2


