Docs: further additions and improvements

docs/reference.rst

@@ -22,14 +22,44 @@ The :func:`expand` class decorator
 
    ―
 
-   The public interface of :func:`expand` includes also the following
-   attributes (making it possible to :ref:`customize how names of
+   The public interface of :func:`expand` includes also the attributes
+   described below.
+
+   Two of them make it possible to :ref:`customize how names of
    parametrized test methods are generated <custom-name-formatting>`):
 
    .. attribute:: expand.global_name_pattern
 
+      :type: :class:`str` or :obj:`None`
+      :value: :obj:`None` (use the default pattern)
+
    .. attribute:: expand.global_name_formatter
 
+      :type: :class:`string.Formatter`-like object or :obj:`None`
+      :value: :obj:`None` (use the default formatter)
+
+   Other two allow -- respectively -- to :ref:`switch the context
+   ordering style <context-order>`, and to decide whether :ref:`a
+   certain deprecated, signature-introspection-based feature
+   <label-and-context-targets-as-kwargs>` shall be enabled:
+
+   .. attribute:: expand.legacy_context_ordering
+
+      :type: :class:`bool`
+      :value: :obj:`True`
+
+   .. attribute:: expand.legacy_signature_introspection
+
+      :type: :class:`bool`
+      :value: :obj:`True`
+
+   .. warning::
+
+      For each of the last two attributes, :obj:`True` (the default
+      value) dictates a deprecated (legacy) behavior, whereas only
+      :obj:`False` is compatible with future versions of
+      *unittest_expander*.
+
 
 The :func:`foreach` method decorator
 ------------------------------------

unittest_expander.py

@@ -1288,7 +1288,7 @@
 True
 
 
-.. _context-order
+.. _context-order:
 
 Context order
 =============
@@ -1343,7 +1343,7 @@
 
 .. warning::
 
-   Here we describe a **deprecated** behavior... Please, read on!
+   Here we describe a **deprecated** behavior... But, please, read on!
 
 .. doctest::
     :hide:
@@ -1435,16 +1435,18 @@
 True
 
 Now the behavior is consistent and always compliant with the
-"higher=outer, lower=inner" rule!
+"higher=outer, lower=inner" rule.
+
+And, also, is forward compatible!
 
 .. warning::
 
-   In the current version of the library the legacy (messy)
+   In the current version of the library, the legacy (messy)
    behavior described earlier is enabled when the global option
    :attr:`expand.legacy_context_ordering` is set to :obj:`True`. Note
-   that -- for the sake of backward compatibility -- it *is* by default
-   (however, in such a case, a deprecation warning will be emitted when
-   it is detected that two or more :func:`foreach` decorators that bring
+   that -- for backward compatibility reasons -- it *is* by default
+   (however, in such a case, a deprecation warning is emitted when it
+   is detected that two or more :func:`foreach` decorators that bring
    contexts are stacked up...). As stated above, you can swich to the
    new behavior (consistently providing the "higher=outer, lower=inner"
    context ordering) by setting :attr:`expand.legacy_context_ordering`
@@ -1485,12 +1487,12 @@
    decorator's machinery detected that the method is able to accept
    ``label`` and/or ``context_targets`` as keyword argument(s).
 
-   In the current version of the library this feature is enabled when
+   In the current version of the library, this feature is enabled when
    the global option :attr:`expand.legacy_signature_introspection` is
-   set to :obj:`True`. Note that -- for the sake of backward
-   compatibility -- it *is* by default (however, a deprecation warning
-   will be emitted when it is detected that your code really makes use
-   of the feature). The feature can be disabled by setting
+   set to :obj:`True`. Note that -- for backward compatibility reasons
+   -- it *is* by default (however, a deprecation warning is emitted when
+   it is detected that your code really makes use of the feature). The
+   feature can be disabled by setting
    :attr:`expand.legacy_signature_introspection` to :obj:`False` (then
    the deprecation warning will not be emitted).