Improved a bit the documentation

2 files changed, 26 insertions, 33 deletions

diff --git a/docs/documentation.md b/docs/documentation.md
index 27b4b99..18aa0e0 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -93,7 +93,7 @@ some experience and it is not as easy as it could be. For instance,
 typical implementations of decorators involve nested functions, and
 we all know that flat is better than nested.
 
-The aim of the ``decorator`` module is to simplify the usage of
+The aim of the ``decorator`` module it to simplify the usage of
 decorators for the average programmer, and to popularize decorators by
 showing various non-trivial examples. Of course, as all techniques,
 decorators can be abused (I have seen that) and you should not try to
@@ -475,9 +475,11 @@ Here is an example of usage:
 
 >>> func()
 calling func with args (), {}
-
 ```
 
+Decorator factories
+-------------------------------------------
+
 The `decorator` function can also be used to define factories of decorators,
 i.e. functions returning decorators. In general you can just write something
 like this:
@@ -490,9 +492,8 @@ def decfactory(param1, param2, ...):
 ```
 
 This is fully general but requires an additional level of nesting. For this
-reason since version 4.2 there is a facility to build
-decorator factories by using a single caller with default arguments i.e.
-writing something like this:
+reason since version 4.2 there is a facility to build decorator factories by
+using a single caller with default arguments i.e. writing something like this:
 
 ```python
 def caller(f, param1=default1, param2=default2, ..., *args, **kw):
@@ -506,22 +507,17 @@ restriction, there exists an unique default decorator, i.e. the member
 of the family which uses the default values for all parameters. Such
 decorator can be written as ``decfactory()`` with no parameters specified;
 moreover, as a shortcut, it is also possible to elide the parenthesis,
-a feature much requested by the users. For years I have been opposite
-to this feature request, since having explicit parenthesis to me is more clear
+a feature much requested by the users. For years I have been opposing
+the request, since having explicit parenthesis to me is more clear
 and less magic; however once this feature entered in decorators of
 the Python standard library (I am referring to the [dataclass decorator](
 https://www.python.org/dev/peps/pep-0557/)) I finally gave up.
 
-The example below will show how it works in practice.
-
-Decorator factories
--------------------------------------------
-
-Sometimes one has to deal with blocking resources, such as ``stdin``.
-Sometimes it is better to receive a "busy" message than just blocking
-everything.
-This can be accomplished with a suitable family of decorators (decorator
-factory), parameterize by a string, the busy message:
+The example below shows how it works in practice. The goal is to
+convert a function relying on a blocking resource into a function
+returning a "busy" message if the resource is not available.
+This can be accomplished with a suitable family of decorators
+parameterize by a string, the busy message:
 
 ```python
 
@@ -1131,7 +1127,7 @@ the dispatch argument simply by passing its name as a string. (Note
 that if you misspell the name you will get an error.)
 
 The decorated function `write` is turned into a generic function (
-`write` is a function at the time it is decorated; it will be turned
+`write` is a function at the idea it is decorated; it will be turned
 into a method later, at class instantiation time),
 and it is called if there are no more specialized implementations.
 
diff --git a/src/tests/documentation.py b/src/tests/documentation.py
index 70f5c3c..4e4ee3d 100644
--- a/src/tests/documentation.py
+++ b/src/tests/documentation.py
@@ -381,6 +381,9 @@ calling func with args (), {}
 
 ```
 
+Decorator factories
+-------------------------------------------
+
 The `decorator` function can also be used to define factories of decorators,
 i.e. functions returning decorators. In general you can just write something
 like this:
@@ -393,9 +396,8 @@ def decfactory(param1, param2, ...):
 ```
 
 This is fully general but requires an additional level of nesting. For this
-reason since version 4.2 there is a facility to build
-decorator factories by using a single caller with default arguments i.e.
-writing something like this:
+reason since version 4.2 there is a facility to build decorator factories by
+using a single caller with default arguments i.e. writing something like this:
 
 ```python
 def caller(f, param1=default1, param2=default2, ..., *args, **kw):
@@ -409,22 +411,17 @@ restriction, there exists an unique default decorator, i.e. the member
 of the family which uses the default values for all parameters. Such
 decorator can be written as ``decfactory()`` with no parameters specified;
 moreover, as a shortcut, it is also possible to elide the parenthesis,
-a feature much requested by the users. For years I have been opposite
-to this feature request, since having explicit parenthesis to me is more clear
+a feature much requested by the users. For years I have been opposing
+the request, since having explicit parenthesis to me is more clear
 and less magic; however once this feature entered in decorators of
 the Python standard library (I am referring to the [dataclass decorator](
 https://www.python.org/dev/peps/pep-0557/)) I finally gave up.
 
-The example below will show how it works in practice.
-
-Decorator factories
--------------------------------------------
-
-Sometimes one has to deal with blocking resources, such as ``stdin``.
-Sometimes it is better to receive a "busy" message than just blocking
-everything.
-This can be accomplished with a suitable family of decorators (decorator
-factory), parameterize by a string, the busy message:
+The example below shows how it works in practice. The goal is to
+convert a function relying on a blocking resource into a function
+returning a "busy" message if the resource is not available.
+This can be accomplished with a suitable family of decorators
+parameterize by a string, the busy message:
 
 $$blocking