Update the MPS Manual for compatibility with Sphinx 3.

gareth-rees · gareth-rees · commit 5078ce192ec5 · 2021-05-27T18:24:37.000+01:00
diff --git a/design/abq.txt b/design/abq.txt
@@ -51,7 +51,7 @@ Interface
 client structures: clients must not depend on its implementation
 details.
 
-``ABQInit(Arena arena, ABQ abq, void *owner, Count elements, Size elementSize)``
+``void ABQInit(Arena arena, ABQ abq, void *owner, Count elements, Size elementSize)``
 
 Initialize the queue ``abq``. The parameter ``arena`` is the arena
 whose control pool should be used to allocate the memory for the
diff --git a/design/bt.txt b/design/bt.txt
@@ -518,8 +518,8 @@ for the following two functions::
        return (i>>5) + (i&31);
     }
 
-``ACT_ON_RANGE(Index base, Index limit, single_action, bits_action, word_action)``
-``ACT_ON_RANGE_HIGH(Index base, Index limit, single_action, bits_action, word_action)``
+``ACT_ON_RANGE(base, limit, single_action, bits_action, word_action)``
+``ACT_ON_RANGE_HIGH(base, limit, single_action, bits_action, word_action)``
 
 _`.iteration`: Many of the following functions involve iteration over
 ranges in a Bit Table. This is performed on whole words rather than
diff --git a/design/buffer.txt b/design/buffer.txt
@@ -544,7 +544,7 @@ itself.
 The pool class's ``bufferDestroy()`` method is called and then the
 buffer structure is uninitialized and freed.
 
-``BufferCheck(Buffer buffer)``
+``Bool BufferCheck(Buffer buffer)``
 
 _`.method.check`: The check method is straightforward, the non-trivial dependencies checked are:
 
@@ -582,7 +582,7 @@ between a reserve and commit. The result is only reliable if the
 client is not currently using the buffer, since it may update the
 alloc and init pointers asynchronously.
 
-``mps_ap_t (BufferAP)(Buffer buffer)``
+``mps_ap_t BufferAP(Buffer buffer)``
 
 Returns the ``APStruct`` substructure of a buffer.
 
@@ -653,7 +653,7 @@ again for any purpose.
 Some classes of pool may cause commit to fail under rare
 circumstances.
 
-``BufferTrip(Buffer buffer, Addr p, Size size)``
+``void BufferTrip(Buffer buffer, Addr p, Size size)``
 
 _`.method.trip`: Act on a tripped buffer. The pool which owns a buffer
 may asynchronously set the buffer limit to zero in order to get
diff --git a/design/clock.txt b/design/clock.txt
@@ -60,13 +60,13 @@ macro must assign a timestamp to ``lvalue`` with the value ``(high
 _`.if.get`: Assign an ``EventClock`` timestamp for the current time to
 ``lvalue``, which is an lvalue with type ``EventClock``.
 
-``EVENT_CLOCK_PRINT(FILE *stream, EventClock clock)``
+``EVENT_CLOCK_PRINT(stream, clock)``
 
 _`.if.print`: Write the value of ``clock`` to the standard C output
 file handle ``stream`` as 16 hexadecimal digits (with leading zeros,
 and capital letters A to F).
 
-``EVENT_CLOCK_WRITE(mps_lib_FILE *stream, EventClock clock)``
+``EVENT_CLOCK_WRITE(stream, clock)``
 
 _`.if.write`: Write the value of ``clock`` to the output stream
 ``stream`` as 16 hexadecimal digits (with leading zeros, and capital
diff --git a/design/fix.txt b/design/fix.txt
@@ -32,7 +32,7 @@ object referred to by the ref (the one that it is supposed to be
 fixing) has not previously been marked (that is, this is the first
 reference to this object that has been fixed), and that the object was
 white (that is, in condemned space), it should (but need not) set the
-field to ``FALSE`` in the passed ``ScanState````wasMarked`` .
+``wasMarked`` field to ``FALSE`` in the passed ``ScanState``.
 
 _`.was-marked.otherwise`: Otherwise, the fix method must
 leave the ``wasMarked`` field unchanged.
diff --git a/design/interface-c.txt b/design/interface-c.txt
@@ -213,7 +213,7 @@ from `mail.richard.1996-08-07.09-49`_.
 ``COMPATLVALUE(lvalue1, lvalue2)``
 
 _`.check.types.compat.lvalue`: This macro checks the assignment
-compatibility of two lvalues. It uses ``sizeof()`` to ensure that the
+compatibility of two lvalues. It uses ``sizeof`` to ensure that the
 assignments have no effect. ::
 
     #define COMPATLVALUE(lv1, lv2) \
@@ -224,7 +224,7 @@ assignments have no effect. ::
 _`.check.types.compat.type`: This macro checks that two types are
 assignment-compatible and equal in size. The hack here is that it
 generates an lvalue for each type by casting zero to a pointer to the
-type. The use of ``sizeof()`` avoids the undefined behaviour that
+type. The use of ``sizeof`` avoids the undefined behaviour that
 would otherwise result from dereferencing a null pointer. ::
 
     #define COMPATTYPE(t1, t2) \
diff --git a/design/locus.txt b/design/locus.txt
@@ -401,7 +401,7 @@ specification to place the new allocation immediately above/below a
 given tract; if that is not possible, it returns ``ResFAIL`` (this
 will make it useful for reallocation functionality).
 
-``ArenaSetTotalLoci(Arena arena, Size nLoci, Size nZoneGroups)``
+``void ArenaSetTotalLoci(Arena arena, Size nLoci, Size nZoneGroups)``
 
 _`.function.set-total`: A function to tell the arena the expected
 number of (non-miscible client) loci, and of zone groups.
diff --git a/design/object-debug.txt b/design/object-debug.txt
@@ -342,7 +342,11 @@ fenceposts around an object. The ``NULL`` method checks tails.
 _`.interface.tags.alloc`: Two functions to extend the existing
 ``mps_alloc()`` (request.???.??? proposes to remove the varargs)
 
-``void (*mps_objects_step_t)(mps_addr_t addr, size_t size, mps_fmt_t format, mps_pool_t pool, void *tag_data, void *p)``
+``typedef void (*mps_objects_step_t)(mps_addr_t addr, size_t size, mps_fmt_t format, mps_pool_t pool, void *tag_data, void *p)``
+
+_`.interface.tags.walker.type`: Type of walker function for
+``mps_pool_walk()`` and ``mps_arena_walk()``.
+
 ``void mps_pool_walk(mps_arena_t arena, mps_pool_t pool, mps_objects_step_t step, void *p)``
 ``void mps_arena_walk(mps_arena_t arena, mps_objects_step_t step, void *p)``
 
diff --git a/design/prmc.txt b/design/prmc.txt
@@ -124,7 +124,7 @@ protection module can single-step the instruction which is causing the
 fault. Return ``TRUE`` if ``MutatorContextStepInstruction()`` is
 capable of single-stepping the instruction, or ``FALSE`` if not.
 
-``Bool Res MutatorContextStepInstruction(MutatorContext context)``
+``Res MutatorContextStepInstruction(MutatorContext context)``
 
 _`.if.step`: Single-step the instruction which is causing the fault.
 Update the mutator context according to the emulation or execution of
diff --git a/design/ring.txt b/design/ring.txt
@@ -122,7 +122,7 @@ parent-children rings it returns the number of children.
 Iteration
 .........
 
-``RING_FOR(Ring node, Ring ring, Ring next)``
+``RING_FOR(node, ring, next)``
 
 _`.for`: A macro is used for iterating over the elements in a ring.
 This macro is called ``RING_FOR()``. ``RING_FOR()`` takes three arguments.
@@ -163,11 +163,11 @@ Element access
 
 _`.next`: ``RingNext()`` returns the next node in the ring.
 
-``Ring (RingPrev)(Ring ring)``
+``Ring RingPrev(Ring ring)``
 
 _`.prev`: ``RingPrev()`` returns the previous node in the ring.
 
-``RING_ELT(type, field, Ring node)``
+``RING_ELT(type, field, node)``
 
 _`.elt`: ``RING_ELT()`` is a macro that converts a pointer to a ring
 structure into a pointer to the enclosing parent structure.
@@ -182,17 +182,17 @@ result is a pointer to the enclosing structure.
 Append / Remove
 ...............
 
-``void RingAppend(Ring ring, Ring new)``
+``void RingAppend(ring, new)``
 
 _`.append`: ``RingAppend()`` appends a singleton ring to a ring (such
 that the newly added element will be last in the iteration sequence).
 
-``void (RingInsert)(Ring ring, Ring new)``
+``void RingInsert(Ring ring, Ring new)``
 
 _`.insert`: ``RingInsert()`` adds a singleton ring to a ring (such that
 the newly added element will be first in the iteration sequence).
 
-``void (RingRemove)(Ring old)``
+``void RingRemove(Ring old)``
 
 _`.remove`: ``RingRemove()`` removes an element from a ring. The newly
 removed element becomes a singleton ring. It is an error for the
diff --git a/design/stack-scan.txt b/design/stack-scan.txt
@@ -256,7 +256,7 @@ entry to the MPS (see `.sol.setjmp`_ and `.sol.stack.nest`_). Return
 _`.if.scan.begin-end`: This function must be called between
 ``STACK_CONTEXT_BEGIN()`` and ``STACK_CONTEXT_END()``.
 
-``STACK_CONTEXT_SAVE(StackContext sc)``
+``STACK_CONTEXT_SAVE(sc)``
 
 _`.if.save`: Store the mutator context in the structure ``sc``.
 
@@ -269,7 +269,7 @@ violation of design.mps.config.no-spaghetti_ in ss.h.
 
 .. _design.mps.config.no-spaghetti: config#.no-spaghetti
 
-``STACK_CONTEXT_BEGIN(Arena arena)``
+``STACK_CONTEXT_BEGIN(arena)``
 
 _`.if.begin`: Start an MPS operation that may need to know the mutator
 context (see `.sol.entry-points`_). This macro must be used like this::
@@ -289,7 +289,7 @@ This macro stores the mutator context in a ``StackContext`` structure
 allocated on the stack, and sets ``arena->stackWarm`` to the hot end
 of the current frame (using `.sol.stack.hot`_).
 
-``STACK_CONTEXT_END(Arena arena)``
+``STACK_CONTEXT_END(arena)``
 
 _`.if.end`: Finish the MPS operation that was started by
 ``STACK_CONTEXT_BEGIN()``.
diff --git a/manual/source/extensions/mps/__init__.py b/manual/source/extensions/mps/__init__.py
@@ -279,9 +279,10 @@ def apply(self):
                     and isinstance(c[0], see)):
                     self.see_only_ids |= ids
 
-        # Add cross-reference targets for plurals.
+        # Add cross-reference targets for plural and capitalized forms.
         objects = self.document.settings.env.domaindata['std']['objects']
-        endings = [(l, l + 's') for l in 'abcedfghijklmnopqrtuvwxz']
+        regular = 'abcedfghijklmnopqrtuvwxz'
+        endings = [(l, l + 's') for l in regular + regular.upper()]
         endings.extend([
             ('ss', 'sses'),
             ('ing', 'ed'),
@@ -299,15 +300,21 @@ def apply(self):
             else:
                 old_fullname = fullname
                 sense = ''
+
+            def maybe_add(new_fullname):
+                new_key = name, new_fullname
+                if new_key not in objects:
+                    objects[new_key] = value
+
+            maybe_add(old_fullname.capitalize())
             if any(old_fullname.endswith(e) for _, e in endings):
                 continue
             for old_ending, new_ending in endings:
                 if not old_fullname.endswith(old_ending):
                     continue
                 new_fullname = '{}{}{}'.format(old_fullname[:len(old_fullname) - len(old_ending)], new_ending, sense)
-                new_key = name, new_fullname
-                if new_key not in objects:
-                    objects[new_key] = value
+                maybe_add(new_fullname)
+                maybe_add(new_fullname.capitalize())
 
     @classmethod
     def warn_indirect_terms(cls, app, exception):
diff --git a/manual/source/extensions/mps/designs.py b/manual/source/extensions/mps/designs.py
@@ -34,13 +34,22 @@
 
 '''
 
+# Macros that are improperly named (not all-caps).
+MACROS = '''
+
+    ClassOfPoly CouldBeA IsA IsSubclass Method MustBeA
+    MustBeA_CRITICAL NextMethod SetClassOfPoly SuperclassPoly
+
+'''
+
 mode = re.compile(r'\.\. mode: .*\n')
 prefix = re.compile(r'^:Tag: ([a-z][a-z.0-9-]*[a-z0-9])$', re.MULTILINE)
 rst_tag = re.compile(r'^:(?:Author|Date|Status|Revision|Copyright|Organization|Format|Index terms|Readership):.*?$\n', re.MULTILINE | re.IGNORECASE)
 mps_tag = re.compile(r'_`\.([a-z][A-Za-z.0-9_-]*[A-Za-z0-9])`:')
 mps_ref = re.compile(r'`(\.[a-z][A-Za-z.0-9_-]*[A-Za-z0-9])`_(?:        )?')
 funcdef = re.compile(r'^``([^`]*\([^`]*\))``$', re.MULTILINE)
-macrodef = re.compile(r'^``([A-Z][A-Z0-9_]+)``$', re.MULTILINE)
+macrodef = re.compile(r'^``((?:[A-Z][A-Z0-9_]+|{})(?:\([^`]*\))?)``$'
+                      .format('|'.join(map(re.escape, MACROS.split()))), re.MULTILINE)
 macro = re.compile(r'``([A-Z][A-Z0-9_]+)``(?:       )?')
 typedef = re.compile(r'^``typedef ([^`]*)``$', re.MULTILINE) 
 func = re.compile(r'``([A-Za-z][A-Za-z0-9_]+\(\))``')
@@ -115,8 +124,8 @@ def convert_file(name, source, dest):
     s = mps_tag.sub(r':mps:tag:`\1`', s)
     s = mps_ref.sub(r':mps:ref:`\1`', s)
     s = typedef.sub(r'.. c:type:: \1', s)
-    s = funcdef.sub(r'.. c:function:: \1', s)
     s = macrodef.sub(r'.. c:macro:: \1', s)
+    s = funcdef.sub(r'.. c:function:: \1', s)
     s = typename.sub(r':c:type:`\1`', s)
     s = func.sub(r':c:func:`\1`', s)
     s = macro.sub(r':c:macro:`\1`', s)
diff --git a/manual/source/guide/lang.rst b/manual/source/guide/lang.rst
@@ -293,7 +293,7 @@ alignment is hard to do portably, because it depends on the target
 architecture and on the way the compiler lays out its structures in
 memory. Here are some things you might try:
 
-#. Some modern compilers support the :c:func:`alignof` operator::
+#. Some modern compilers support the ``alignof`` operator::
 
         #define ALIGNMENT alignof(obj_s)
 
@@ -575,8 +575,7 @@ following code must be added to :c:func:`obj_scan` and
     design of the forwarding object. In the toy Scheme interpreter,
     this happens on some 64-bit platforms, where a pointer is 8 bytes
     long, and a :c:type:`character_s` object (which consists of a
-    4-byte :c:type:`int` and a 1-byte :c:type:`char`) is also 8 bytes
-    long.
+    4-byte ``int`` and a 1-byte ``char``) is also 8 bytes long.
 
     There are a couple of solutions to this problem:
 
diff --git a/manual/source/pool/ams.rst b/manual/source/pool/ams.rst
@@ -118,7 +118,7 @@ AMS interface
       the :term:`generation chain` for the pool. If not specified, the
       pool will use the arena's default chain.
 
-    * :c:macro:`MPS_KEY_GEN` (type :c:type:`unsigned`) specifies the
+    * :c:macro:`MPS_KEY_GEN` (type ``unsigned``) specifies the
       :term:`generation` in the chain into which new objects will be
       allocated. If you pass your own chain, then this defaults to
       ``0``, but if you didn't (and so use the arena's default chain),
diff --git a/manual/source/pool/awl.rst b/manual/source/pool/awl.rst
@@ -333,7 +333,7 @@ AWL interface
       the :term:`generation chain` for the pool. If not specified, the
       pool will use the arena's default chain.
 
-    * :c:macro:`MPS_KEY_GEN` (type :c:type:`unsigned`) specifies the
+    * :c:macro:`MPS_KEY_GEN` (type ``unsigned``) specifies the
       :term:`generation` in the chain into which new objects will be
       allocated. If you pass your own chain, then this defaults to
       ``0``, but if you didn't (and so use the arena's default chain),
diff --git a/manual/source/pool/lo.rst b/manual/source/pool/lo.rst
@@ -121,7 +121,7 @@ LO interface
       the :term:`generation chain` for the pool. If not specified, the
       pool will use the arena's default chain.
 
-    * :c:macro:`MPS_KEY_GEN` (type :c:type:`unsigned`) specifies the
+    * :c:macro:`MPS_KEY_GEN` (type ``unsigned``) specifies the
       :term:`generation` in the chain into which new objects will be
       allocated. If you pass your own chain, then this defaults to
       ``0``, but if you didn't (and so use the arena's default chain),
diff --git a/manual/source/pool/mvff.rst b/manual/source/pool/mvff.rst
@@ -121,7 +121,7 @@ MVFF interface
       and the maximum is the arena grain size
       (see :c:macro:`MPS_KEY_ARENA_GRAIN_SIZE`).
 
-    * :c:macro:`MPS_KEY_SPARE` (type :c:type:`double`, default 0.75)
+    * :c:macro:`MPS_KEY_SPARE` (type ``double``, default 0.75)
       is the maximum proportion of memory that the pool will keep
       spare for future allocations. If the proportion of memory that's
       free exceeds this, then the pool will return some of it to the
diff --git a/manual/source/pool/mvt.rst b/manual/source/pool/mvt.rst
@@ -165,16 +165,16 @@ MVT interface
       object population does vary, at a slight cost in efficiency. The
       reserve does not guarantee any particular amount of allocation.
 
-    * :c:macro:`MPS_KEY_MVT_FRAG_LIMIT` (type :c:type:`double`,
-      default 0.3) is a double from 0.0 to 1.0 (inclusive). It sets an
-      upper limit on the space overhead of an MVT pool, in case block
-      death times and allocations do not correlate well. If the free
-      space managed by the pool as a ratio of all the space managed by
-      the pool exceeds the fragmentation limit, the pool falls back to a
-      first fit allocation policy, exploiting space more efficiently at
-      a cost in time efficiency. A fragmentation limit of 0.0 would
-      cause the pool to operate as a first-fit pool, at a significant
-      cost in time efficiency: therefore this is not permitted.
+    * :c:macro:`MPS_KEY_MVT_FRAG_LIMIT` (type ``double``, default 0.3)
+      may range from 0.0 to 1.0 (inclusive). It sets an upper limit on
+      the space overhead of an MVT pool, in case block death times and
+      allocations do not correlate well. If the free space managed by
+      the pool as a ratio of all the space managed by the pool exceeds
+      the fragmentation limit, the pool falls back to a first fit
+      allocation policy, exploiting space more efficiently at a cost
+      in time efficiency. A fragmentation limit of 0.0 would cause the
+      pool to operate as a first-fit pool, at a significant cost in
+      time efficiency: therefore this is not permitted.
 
       A fragmentation limit of 1.0 causes the pool to always use
       temporal fit (unless resources are exhausted). If the objects
diff --git a/manual/source/topic/allocation.rst b/manual/source/topic/allocation.rst
@@ -293,11 +293,11 @@ is thus::
         :c:func:`mps_reserve` is implemented as a macro for speed. It
         may evaluate its arguments multiple times.
 
-        There is an alternative, :c:func:`MPS_RESERVE_BLOCK`, which
+        There is an alternative, :c:macro:`MPS_RESERVE_BLOCK`, which
         may generate faster code on some compilers.
 
 
-.. c:function:: MPS_RESERVE_BLOCK(mps_res_t res_v, mps_addr_t *p_v, mps_ap_t ap, size_t size)
+.. c:macro:: MPS_RESERVE_BLOCK(res_v, p_v, ap, size)
 
     An alternative to :c:func:`mps_reserve`. On compilers that do not
     perform common-subexpression elimination, it may generate faster
diff --git a/manual/source/topic/arena.rst b/manual/source/topic/arena.rst
@@ -154,9 +154,9 @@ Client arenas
       ``sizeof(void *)``. Larger granularity reduces overheads, but
       increases :term:`fragmentation` and :term:`retention`.
 
-    * :c:macro:`MPS_KEY_PAUSE_TIME` (type :c:type:`double`, default
-      0.1) is the maximum time, in seconds, that operations within the
-      arena may pause the :term:`client program` for. See
+    * :c:macro:`MPS_KEY_PAUSE_TIME` (type ``double``, default 0.1) is
+      the maximum time, in seconds, that operations within the arena
+      may pause the :term:`client program` for. See
       :c:func:`mps_arena_pause_time_set` for details.
 
     For example::
@@ -262,16 +262,16 @@ Virtual memory arenas
       that's smaller than the operating system page size, the MPS
       rounds it up to the page size and continues.
 
-    * :c:macro:`MPS_KEY_SPARE` (type :c:type:`double`, default 0.75)
-      is the maximum proportion of committed memory that the arena
-      will keep spare for future allocations.  If the proportion of
-      spare committed memory exceeds this, then the arena will return
-      some of it to the operating system for use by other processes.
-      See :c:func:`mps_arena_spare` for details.
+    * :c:macro:`MPS_KEY_SPARE` (type ``double``, default 0.75) is the
+      maximum proportion of committed memory that the arena will keep
+      spare for future allocations. If the proportion of spare
+      committed memory exceeds this, then the arena will return some
+      of it to the operating system for use by other processes. See
+      :c:func:`mps_arena_spare` for details.
 
-    * :c:macro:`MPS_KEY_PAUSE_TIME` (type :c:type:`double`, default
-      0.1) is the maximum time, in seconds, that operations within the
-      arena may pause the :term:`client program` for. See
+    * :c:macro:`MPS_KEY_PAUSE_TIME` (type ``double``, default 0.1) is
+      the maximum time, in seconds, that operations within the arena
+      may pause the :term:`client program` for. See
       :c:func:`mps_arena_pause_time_set` for details.
 
     A sixth optional :term:`keyword argument` may be passed, but it
diff --git a/manual/source/topic/cache.rst b/manual/source/topic/cache.rst
diff --git a/manual/source/topic/deprecated.rst b/manual/source/topic/deprecated.rst
diff --git a/manual/source/topic/format.rst b/manual/source/topic/format.rst
diff --git a/manual/source/topic/interface.rst b/manual/source/topic/interface.rst
diff --git a/manual/source/topic/keyword.rst b/manual/source/topic/keyword.rst
diff --git a/manual/source/topic/plinth.rst b/manual/source/topic/plinth.rst
diff --git a/manual/source/topic/root.rst b/manual/source/topic/root.rst
diff --git a/manual/source/topic/scanning.rst b/manual/source/topic/scanning.rst

Original file line number	Diff line number	Diff line change
`@@ -518,8 +518,8 @@ for the following two functions::`
`518`	`518`	`return (i>>5) + (i&31);`
`519`	`519`	`}`
`520`	`520`
`521`		-``ACT_ON_RANGE(Index base, Index limit, single_action, bits_action, word_action)``
`522`		-``ACT_ON_RANGE_HIGH(Index base, Index limit, single_action, bits_action, word_action)``
	`521`	+``ACT_ON_RANGE(base, limit, single_action, bits_action, word_action)``
	`522`	+``ACT_ON_RANGE_HIGH(base, limit, single_action, bits_action, word_action)``
`523`	`523`
`524`	`524`	_`.iteration`: Many of the following functions involve iteration over
`525`	`525`	`ranges in a Bit Table. This is performed on whole words rather than`