Docs: a few improvements more...

docs/reference.rst

@@ -106,23 +106,24 @@ The :class:`paramseq` class
    .. method:: __add__(param_collection)
 
       Returns a new :class:`paramseq` instance -- being a result of
-      concatenation of the current :class:`paramseq` instance and given
-      *param_collection* (see the description of the :class:`paramseq`
-      constructor's argument *param_collection*...).
+      concatenation of the :class:`paramseq` instance we operate on
+      and the given *param_collection* (see the description of the
+      :class:`paramseq` constructor's argument *param_collection*...).
 
    .. method:: __radd__(param_collection)
 
       Returns a new :class:`paramseq` instance -- being a result of
-      concatenation of given *param_collection* (see the description of
-      the :class:`paramseq` constructor's argument *param_collection*...)
-      and the current :class:`paramseq` instance.
+      concatenation of the given *param_collection* (see the description
+      of the :class:`paramseq` constructor's argument
+      *param_collection*...) and the :class:`paramseq` instance we
+      operate on.
 
    .. method:: context(context_manager_factory, \
                        *its_args, **its_kwargs, \
                        _enable_exc_suppress_=False)
 
       Returns a new :class:`paramseq` instance containing clones
-      of the items of the current instance -- each cloned with a
+      of the items of the instance we operate on -- each cloned with a
       :meth:`param.context` call (see below), to which all given
       arguments are passed.
 
@@ -149,8 +150,8 @@ The :class:`param` class
                        _enable_exc_suppress_=False)
 
       Returns a new :class:`param` instance being a clone of the
-      current instance, with the specified context manager factory
-      (and its arguments) attached.
+      the instance we operate on, with the specified context manager
+      factory (and its arguments) attached.
 
       By default, the possibility to suppress exceptions by returning
       a *true* value from context manager's :meth:`__exit__` is
@@ -162,7 +163,7 @@ The :class:`param` class
    .. method:: label(text)
 
       Returns a new :class:`param` instance being a clone of the
-      current instance, with the specified textual label attached.
+      instance we operate on, with the specified textual label attached.
 
 
 Non-essential constants and classes

unittest_expander.py

@@ -348,13 +348,13 @@
 
 .. note::
 
-   Parameter collections -- such as *sequences* (e.g., :class:`list`
-   instances), *mappings* (e.g., :class:`dict` instances), *sets*
-   (e.g., :class:`set` or :class:`frozenset` instances) or just ready
-   :class:`paramseq` instances -- do not need to be created or bound
-   within the test class body; you could, for example, import them from
-   a separate module. Obviously, that makes data/code reuse and
-   refactorization easier.
+   Parameter collections -- being *sequences* (e.g., :class:`list`
+   instances), or *mappings* (e.g., :class:`dict` instances), or *sets*
+   (e.g., :class:`set` or :class:`frozenset` instances), or callable
+   objects (see below...), or just ready :class:`paramseq` instances --
+   do not need to be created or bound within the test class body; you
+   could, for example, import them from a separate module. Obviously,
+   that makes data/code reuse and refactorization easier.
 
    Also, note that the call signatures of :func:`foreach` and the
    :class:`paramseq` constructor are identical: you pass in either
@@ -422,15 +422,16 @@
 
 A callable object (such as the :term:`generator` function in the example
 above) which is passed to the :class:`paramseq`'s constructor (or
-directly to :func:`foreach`) can accept either no arguments or one
+directly to :func:`foreach`) should accept either no arguments or one
 positional argument -- in the latter case the *test class* will be
 passed in.
 
 .. note::
 
    The callable object will be called -- and its *iterable* result will
    be iterated over (consumed) -- *when* the :func:`expand` decorator
-   is being executed, *before* generating parametrized test methods.
+   is being executed, *directly before* generating parametrized test
+   methods.
 
    What should also be emphasized is that those operations (the
    aforementioned call and iterating over its result) will be
@@ -1430,7 +1431,7 @@
 
 :func:`expand` does its best to avoid name conflicts: when it detects
 that a newly generated name could clash with an existing name (whether
-the latter was generated recently -- by the current application of
+the latter was generated recently -- by the ongoing application of
 :func:`expand` -- or might have already existed), it adds a suffix
 to the newly generated name to avoid the clash.  E.g.: