--- a/rset.py	Tue Sep 07 17:34:42 2010 +0200
+++ b/rset.py	Mon Sep 13 15:15:21 2010 +0200
@@ -569,7 +569,8 @@
                     if i == col:
                         continue
                     coletype = self.description[row][i]
-                    # None description possible on column resulting from an outer join
+                    # None description possible on column resulting from an
+                    # outer join
                     if coletype is None or eschema(coletype).final:
                         continue
                     try:
@@ -588,11 +589,20 @@
 
     @cached
     def related_entity(self, row, col):
-        """try to get the related entity to extract format information if any"""
+        """given an cell of the result set, try to return a (entity, relation
+        name) tuple to which this cell is linked.
+
+        This is especially useful when the cell is an attribute of an entity,
+        to get the entity to which this attribute belongs to.
+        """
         rqlst = self.syntax_tree()
+        # UNION query, we've first to find a 'pivot' column to use to get the
+        # actual query from which the row is coming
         etype, locate_query_col = self._locate_query_params(rqlst, row, col)
-        # UNION query, find the subquery from which this entity has been found
+        # now find the query from which this entity has been found. Returned
+        # select node may be a subquery with different column indexes.
         select = rqlst.locate_subquery(locate_query_col, etype, self.args)[0]
+        # then get the index of root query's col in the subquery
         col = rqlst.subquery_selection_index(select, col)
         if col is None:
             # XXX unexpected, should fix subquery_selection_index ?