[doc] proofreading the guides, refactoring the reference.

bonobo/constants.py

@@ -1,6 +1,28 @@
-class Token:
-    """Factory for signal oriented queue messages or other token types."""
+"""
+.. data:: BEGIN
 
+    **BEGIN** token marks the entrypoint of graphs, and all extractors will be connected to this node.
+
+    Without this, it would be impossible for an execution to actually start anything, as it's the marker that tells
+    |bonobo| which node to actually call when the execution starts.
+
+.. data:: NOT_MODIFIED
+
+    **NOT_MODIFIED** is a special value you can return or yield from a transformation to tell bonobo to reuse
+    the input data as output.
+
+    As a convention, all loaders should return this, so loaders can be chained.
+
+.. data:: EMPTY
+
+    Shortcut for "empty tuple". It's often much more clear to write (especially in a test) `write(EMPTY)` than
+    `write(())`, although strictly equivalent.
+
+
+"""
+
+
+class Token:
     def __init__(self, name):
         self.__name__ = name
 
@@ -8,16 +30,15 @@ class Token:
         return '<{}>'.format(self.__name__)
 
 
-BEGIN = Token('Begin')
-END = Token('End')
-
-
 class Flag(Token):
     must_be_first = False
     must_be_last = False
     allows_data = True
 
 
+BEGIN = Token('Begin')
+END = Token('End')
+
 INHERIT = Flag('Inherit')
 NOT_MODIFIED = Flag('NotModified')
 NOT_MODIFIED.must_be_first = True