Doc fixes

1 files changed, 15 insertions, 11 deletions

diff --git a/docs/documentation.md b/docs/documentation.md
index 2c0db63..72ab411 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -111,19 +111,20 @@ can be used as a decorator. However, this definition is somewhat too large
 to be really useful. It is more convenient to split the generic class of
 decorators in two subclasses:
 
-*signature-preserving* decorators:
-    Callable objects which accept a function as input and return
-    a function as output, *with the same signature*.
-*signature-changing* decorators:
-    Decorators which change the signature of their input function,
-    or decorators that return non-callable objects.
-
-**Signature-changing** decorators have their use: for instance, the
+1. **signature-preserving decorators**, callable objects which accept
+    a function as input and return a function as output, *with the
+    same signature*
+
+2. **signature-changing** decorators, i.e. decorators
+    which change the signature of their input function, or decorators
+    that return non-callable objects
+
+Signature-changing decorators have their use: for instance, the
 builtin classes ``staticmethod`` and ``classmethod`` are in this
 group. They take functions and return descriptor objects which
 are neither functions, nor callables.
 
-Still, **signature-preserving** decorators are more common, and easier
+Still, signature-preserving decorators are more common, and easier
 to reason about. In particular, they can be composed together,
 whereas other decorators generally cannot.
 
@@ -218,7 +219,7 @@ Python 3.5. This is pretty bad: ``pydoc`` will tell you that the
 function accepts the generic signature ``*args, **kw``, but
 calling the function with more than one argument raises an error:
 
-```
+```python
 >>> f1(0, 1) 
 Traceback (most recent call last):
    ...
@@ -371,7 +372,8 @@ FullArgSpec(args=['x', 'y', 'z'], varargs='args', varkw='kw', defaults=(1, 2), k
 Function annotations
 ---------------------------------------------
 
-Python 3 introduced the concept of `function annotations`_: the ability
+Python 3 introduced the concept of [function annotations](
+http://www.python.org/dev/peps/pep-3107/): the ability
 to annotate the signature of a function with additional information,
 stored in a dictionary named ``__annotations__``. The ``decorator`` module
 (starting from release 3.3) will understand and preserve these annotations.
@@ -609,6 +611,8 @@ TypeError: You are decorating a non function: <class '__main__.User'>
 
 ```
 
+Be careful!
+
 ``decorator(cls)``
 --------------------------------------------