Documentation, including _qualified_name() woes.

README.rst

@@ -69,7 +69,13 @@ the line number where it should be inserted::
     # documentation string is done by:
     # src[:line_number] + docstring + src[line_number:]
 
+There is a CLI interface ``typin/src/typin/typin_cli.py`` to execute arbitrary
+python code using ``compile()`` and ``exec()`` like this::
+    
+    python typin_cli.py --stubs=stubs -- example.py 'foo bar baz'
 
+This will ``compile()/exec()`` ``example.py`` with the arguments ``foo bar baz``
+and dump out the results.
 
 .. image:: https://img.shields.io/pypi/v/typin.svg
         :target: https://pypi.python.org/pypi/typin

src/typin/type_inferencer.py

@@ -274,6 +274,20 @@ def _strip_locals_from_qualified_name(self, qualified_name):
         return qualified_name[idx + len('<locals>') + 1:]
 
     def _qualified_name(self, frame):
+        """This takes a frame and discovers which function is being executed.
+        It then returns the qualified name of the function as a string and the
+        base classes (as a tuple of types) of the enclosing object (if any).
+        
+        This pretty flakey for a number of reasons:
+        
+        * It searches the whole garbage collector for live functions that match.
+          This is really expensive, surely there is a better way?
+        * It frequently fails to discover base class types for reasons not yet
+          well understood.
+
+        If this can be made more reliable then cacheing could help to make the
+        performance problem go away. 
+        """
         # The qualified name of the function 
         q_name = ''
         bases = None

src/typin/typin_cli.py

@@ -68,7 +68,7 @@ def main():
     for each function records all the types called, returned and raised.
     For example::
 
-        python typin_cli.py --stubs=stubs example.py foo bar baz
+        python typin_cli.py --stubs=stubs -- example.py 'foo bar baz'
 
     This will execute ``example.py`` with the options ``foo bar baz`` under the
     control of typin and write all the type annotations to the stubs/ directory.