preprocessor_docs (#12)

* Added docstrings to Preprocessor class

* Add preprocessor documentation

docs/contributing.rst

@@ -35,13 +35,55 @@ Internals
 
 The code is separated in several components:
 
+* `Preprocessor`_
 * `Parser`_
 * `Syntax tree`_
 * `Snippet provider`_
 * `Compiler`_
 * `Utilities`_
 * `Application frontend`_
 
+Preprocessor
+^^^^^^^^^^^^
+
+Before parsing and creating syntax tree some prepossessing is done to enable some feathers.
+
+Decorators
+""""""""""
+
+Consider flowing example:
+
+.. code-block:: text
+
+   1. for#int$i%n
+   2. for[[sup]]
+
+And flowing snippet definition:
+
+.. code-block:: json
+
+    {"name": "sup","language": "C++","snippet": "#int$i%n"}
+
+This pattern occurs often and it is useful to name it and use it by name ('sub' stands for 'standard up').
+More realistic examples are design pattern implementation (singleton for example).
+Another advantage of this approach is that multiple decorators can be combined to make a more complex construction.
+
+Preprocessor detects decorators that are defined in double square brackets and expands them using snippet provider.
+
+Cursor marker
+"""""""""""""
+
+After expanding a snippet user should have the cursor at a convenient location.
+The following rule is followed.
+
+
+*Writing some text after expanding the snippet should have the same effect as
+writing that text and expanding the snippet afterwords.*
+
+
+To enable this preprocessor appends :code:`&[{cursor_marker}]` to the snippet text
+so a plugin can put cursor at the marker location.
+
 Parser
 ^^^^^^
 

homotopy/preprocessor.py

@@ -4,15 +4,30 @@
 
 
 class Preprocessor:
+    """
+    Prepossess snippet text to enable extra feathers.
+    """
     cursor_marker = "[{cursor_marker}]"
 
     @staticmethod
     def expand_decorators(snippet_text):
+        """
+        Expand decorators to enable concise writing of common patterns.
+
+        :param snippet_text: Snippet text
+        :return: Expanded snippet text
+        """
         return re.sub(
                 r'\[\[(.*?)\]\]',
                 lambda match_group: snippetProvider[match_group.group(1)],
                 snippet_text)
 
     @staticmethod
     def put_cursor_marker(snippet_text):
+        """
+        Put cursor marker witch should be used by editor plugins for better experience.
+
+        :param snippet_text: Snippet text
+        :return: Snippet text with marker at the end
+        """
         return snippet_text + "&" + Preprocessor.cursor_marker