DOC(modifs): explain Diacritics, +term synonym

Author: ankostis

docs/source/arch.rst

@@ -252,7 +252,7 @@ Architecture
           - operation *needs* & *provides* are zipped against the underlying function's
             arguments and results.
 
-          These matchings are affected by `modifier`\s.
+          These matchings are affected by `modifier`\s, print-out with `diacritic`\s.
 
     needs
     fn_needs
@@ -299,10 +299,15 @@ Architecture
         over which `outputs` were actually produced, or to cancel `sideffects`.
 
     modifier
+    diacritic
         A `modifier` change `dependency` behavior during `compilation` or `execution`.
 
         For instance, `needs` may be annotated as `optionals` function arguments,
-        `provides` and *needs* can be annotated as "ghost" `sideffects`
+        `provides` and *needs* can be annotated as "ghost" `sideffects`.
+
+        .. include:: ../../graphtik/modifiers.py
+            :start-after: .. diacritics-start
+            :end-before: .. diacritics-end
 
         See :mod:`graphtik.modifiers` module.
 
@@ -331,6 +336,8 @@ Architecture
             :start-after: .. varargs-mistake-start
             :end-before: .. varargs-mistake-end
 
+        In printouts, it is denoted either with ``*`` or ``+`` `diacritic`.
+
     sideffects
         A `modifier` denoting a fictive `dependency` linking `operation`\s into virtual flows,
         without real data exchanges.
@@ -342,6 +349,7 @@ Architecture
 
         - An *abstract sideffect* modifier (annotated with :func:`.sfx`)
           describing modifications taking place beyond the scope of the solution.
+          It may have just the "optional" `diacritic` in printouts.
 
         - The `sideffected` modifier (annotated with :func:`.sfxed`)
           denoting modifications on a *real* dependency read from and written to
@@ -367,7 +375,8 @@ Architecture
         the *sideffected dependency* is declared both as *needs* and *provides*
         of some operation.
 
-        It is annotated with :func:`.sfxed`.
+        It is annotated with :func:`.sfxed`;  it may have all `diacritic`\s
+        in printouts.
 
     reschedule
     rescheduling

graphtik/modifiers.py

@@ -10,6 +10,20 @@
     This module (along with :mod:`.op` & :mod:`.pipeline`) is what client code needs
     to define pipelines *on import time* without incurring a heavy price
     (~7ms on a 2019 fast PC)
+
+**Diacritics**
+
+.. diacritics-start
+
+When printed, *modifiers* annotate regular or sideffect dependencies with
+these **diacritics**::
+
+    >   : mapped (fn_keyword)
+    ?   : optional (fn_keyword)
+    *   : vararg
+    +   : varargs
+
+.. diacritics-end
 """
 import enum
 from typing import Optional, Tuple, Union

graphtik/op.py

@@ -221,6 +221,7 @@ class FunctionalOperation(Operation, Plottable):
     .. Tip::
         - Use :func:`.operation()` factory to build instances of this class instead.
         - Call :meth:`withset()` on existing instances to re-configure new clones.
+        - See :term:`diacritic`\\s to understand printouts of this class.
     """
 
     def __init__(
@@ -343,7 +344,7 @@ def __hash__(self):
 
     def __repr__(self):
         """
-        Display more informative names for the Operation class
+        Display operation & dependency names annotated with :term:`diacritic`\\s.
         """
         from .config import (
             is_debug,

graphtik/pipeline.py

@@ -59,8 +59,9 @@ class Pipeline(Operation, Plottable):
     An operation that can :term:`compute` a network-graph of operations.
 
     .. Tip::
-        Use :func:`compose()` factory to prepare the `net` and build
-        instances of this class.
+        - Use :func:`compose()` factory to prepare the `net` and build
+          instances of this class.
+        - See :term:`diacritic`\\s to understand printouts of this class.
     """
 
     #: The name for the new pipeline, used when nesting them.