extend documentation of type system (more on creating a new type)

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/type-system.md b/doc/type-system.md
index d1982a1..9b4a2ed 100644
--- a/doc/type-system.md
+++ b/doc/type-system.md
@@ -76,5 +76,38 @@ The number argument to the `Type` constructor can have an
 arbitrary value, as long as it is different from the value of
 every other `Type` object.
 
+You also need to tell the type system how to recognize runtime
+objects that belong to your type. Add one or several new `elif`
+clauses to the `get_type` function. E.g., if you are defining a
+new type for dictionaries, you would add the clauses
+
+    elif isinstance(x, dict):
+        return (TYPE_DICT, False)
+    elif isinstance(x, ast.Dict):
+        return (TYPE_DICT, True)
+
+The second item of the tuple that `get_type` returns indicates
+whether `x` is an AST (Abstract Syntax Tree) or not. Only
+instances of subclasses of `ast.AST` are ASTs.
+
 Optionally, you can add converters for the new type. You can do
 so by extending the dictionary `TYPE_CONVERTERS` in `tatype.py`.
+The format is quite simple: To add a converter from your type to
+e.g., TYPE_FLOAT, add the entry:
+
+    TYPE_CONVERTERS = {
+       # ...
+       TYPE_MYTYPE: {
+           # ...
+           TYPE_FLOAT: float
+           # ...
+       }
+       # ...
+    }
+
+Note that it is not obligatory to use the function `float` as
+the converter to the type TYPE_FLOAT. In fact, you can use any
+function or method. Please make sure that the converter accepts
+arguments of the source type (here, TYPE_MYTYPE) and returns a
+value of the target type (here, TYPE_FLOAT). The converter must
+not throw any errors.