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)
+
+   The 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` (which is 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:
@@ -1443,8 +1443,8 @@
    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
+   (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`
@@ -1489,8 +1489,8 @@
    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
+   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).