docs: explain elaboration, elaboratables, and submodules.

Co-authored-by: mcclure <mcclure@users.noreply.github.com>

docs/lang.rst

@@ -1300,7 +1300,7 @@ If the name of the domain is not known upfront, another, less concise, syntax ca
 
     add_video_domain(2)
 
-.. tip::
+.. note::
 
     Whenever the created :class:`ClockDomain` object is immediately assigned using the :pc:`domain_name = ClockDomain(...)` or :pc:`m.domains.domain_name = ClockDomain(...)` syntax, the name of the domain may be omitted from the :pc:`ClockDomain()` invocation. In other cases, it must be provided as the first argument.
 
@@ -1375,15 +1375,65 @@ The :class:`ClockSignal` and :class:`ResetSignal` values may also be assigned to
 Elaboration
 ===========
 
-.. todo:: Write this section.
+Amaranth designs are built from a hierarchy of smaller subdivisions, which are called *elaboratables*. The process of creating a data structure representing the behavior of a complete design by composing such subdivisions together is called *elaboration*.
+
+An elaboratable is any Python object that inherits from the :class:`Elaboratable` base class and implements the ``elaborate``  method:
+
+.. testcode::
+
+    class Counter(Elaboratable):
+        def elaborate(self, platform):
+            m = Module()
+
+            ...
+
+            return m
+
+The ``elaborate`` method must either return an instance of :class:`Module` to describe the behavior of the elaboratable, or delegate it by returning another elaboratable object.
+
+.. note::
+
+    Instances of :class:`Module` also implement the ``elaborate`` method, which returns a special object that represents a fragment of a netlist. Such an object cannot be constructed without using :class:`Module`.
+
+The :pc:`platform` argument received by the ``elaborate`` method can be :pc:`None`, an instance of :ref:`a built-in platform <platform>`, or a custom object. It is used for `dependency injection <https://en.wikipedia.org/wiki/Dependency_injection>`_ and to contain the state of a design while it is being elaborated.
+
+.. important::
+
+    The ``elaborate`` method should not modify the ``self`` object it receives other than for debugging and experimentation. Elaborating the same design twice with two identical platform objects should produce two identical netlists. If the design needs to be modified after construction, this should happen before elaboration.
+
+    It is not possible to ensure that a design which modifies itself during elaboration is correctly converted to a netlist because the relative order in which the ``elaborate`` methods are called within a single design is not guaranteed.
+
+The Amaranth standard library provides *components*: elaboratable objects that also include a description of their interface. Unless otherwise necessary, an elaboratable should inherit from :class:`amaranth.lib.wiring.Component` rather than plain :class:`Elaboratable`. See the :ref:`introduction to interfaces and components <wiring-introduction>` for details.
 
 
-.. _lang-domainrenamer:
+.. _lang-submodules:
 
-Renaming domains
-----------------
+Submodules
+----------
 
-.. todo:: Write this section about :class:`DomainRenamer`
+An elaboratable can be included within another elaboratable by adding it as a submodule:
+
+.. testcode::
+
+    m.submodules.counter = counter = Counter()
+
+If the name of a submodule is not known upfront, a different syntax should be used:
+
+.. testcode::
+
+    for n in range(3):
+        m.submodules[f"counter_{n}"] = Counter()
+
+A submodule can also be added without specifying a name:
+
+.. testcode::
+
+    counter = Counter()
+    m.submodules += counter
+
+.. tip::
+
+    If a name is not explicitly specified for a submodule, one will be generated and assigned automatically. Designs with many autogenerated names can be difficult to debug, so a name should usually be supplied.
 
 
 .. _lang-controlinserter:
@@ -1394,10 +1444,18 @@ Modifying control flow
 .. todo:: Write this section about :class:`ResetInserter` and :class:`EnableInserter`
 
 
+.. _lang-domainrenamer:
+
+Renaming domains
+----------------
+
+.. todo:: Write this section about :class:`DomainRenamer`
+
+
 .. _lang-memory:
 
-Memory arrays
-=============
+Memories
+========
 
 .. todo:: Write this section.
 

docs/platform.rst

@@ -1,3 +1,5 @@
+.. _platform:
+
 Platform integration
 ####################