[pypy-commit] pypy default: Try to document the complicated API of emulate_pbc_call().

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r77043:194c10be7277
Date: 2015-05-04 17:58 +0200
http://bitbucket.org/pypy/pypy/changeset/194c10be7277/

Log:	Try to document the complicated API of emulate_pbc_call().

diff --git a/rpython/annotator/bookkeeper.py b/rpython/annotator/bookkeeper.py
--- a/rpython/annotator/bookkeeper.py
+++ b/rpython/annotator/bookkeeper.py
@@ -525,6 +525,24 @@
         return s_result
 
     def emulate_pbc_call(self, unique_key, pbc, args_s, replace=[], callback=None):
+        """For annotating some operation that causes indirectly a Python
+        function to be called.  The annotation of the function is "pbc",
+        and the list of annotations of arguments is "args_s".
+
+        Can be called in various contexts, but from compute_annotation()
+        or compute_result_annotation() of an ExtRegistryEntry, call it
+        with both "unique_key" and "callback" set to
+        "self.bookkeeper.position_key".
+
+        In general, "unique_key" should somehow uniquely identify where
+        the call is in the source code, and "callback" can be either a
+        position_key to reflow from when we see more general results,
+        or a real callback function that will be called with arguments
+        # "(annotator, called_graph)" whenever the result is generalized.
+
+        "replace" can be set to a list of old unique_key values to
+        forget now, because the given "unique_key" replaces them.
+        """
         emulate_enter = not hasattr(self, 'position_key')
         if emulate_enter:
             self.enter(None)