[py-svn] r33461 - py/dist/py/documentation/apigen

[fijal at codespeak.net]

Author: fijal
Date: Thu Oct 19 16:28:36 2006
New Revision: 33461

Added:
   py/dist/py/documentation/apigen/first-implementation.txt   (contents, props changed)
Log:
Added some notes.


Added: py/dist/py/documentation/apigen/first-implementation.txt
==============================================================================
--- (empty file)
+++ py/dist/py/documentation/apigen/first-implementation.txt	Thu Oct 19 16:28:36 2006
@@ -0,0 +1,34 @@
+
+Automatic API documentation generation - first outcome
+======================================================
+
+After the first implementation of API generation tool,
+I've realised that there are several shortcoming in current
+attempt.
+
+First of all, we need to define our type system. The one presented
+in PyPy is just to weak to our purpose. This will not be very easy
+issue anyway. Basic ideas are very much like the PyPy one, but
+from the beggining we want to support all rich python typesystem, not
+only the subset of it. So we need to provide informations which are
+valuable for the end user (quite rich type system) and can always
+work. I don't think that actuall tracking of all possible values of
+objects makes sense. User might see them in call sites if he really wants
+to.
+
+Second thing is that we need some kind of structure (we do lack such
+attempt now), which can group several classes/functions/objects into
+a module (split by '.' or whatever).
+
+Another thing is that we need to support any possible object which
+are actually exported (well, we might assume that objects which
+are exported are to some extend constants).
+
+We need to track somehow several objects, which are not entirely
+Python user-build objects. This means probably: builtin functions,
+classes with builtin __init__, etc. etc.
+
+And as well implement stuff like c_call, c_return and such.
+
+I guess that keeping track of side effects might happen at some point
+in the future, but it's not *now*.