# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@logilab.fr>
# Date 1318491854 -7200
# Node ID 1faa8edb5ae3052e7d12a598215ae1c9e76b3240
# Parent  018b5deca73ee708ea7a98eda07c1f3fbd581587
init_facets: Add documentation

init_facets is not included in the default sphinx documentation but this
docstring should help people digging into cubicweb core. This could go in an
Advanced developer section of the book.

diff -r 018b5deca73e -r 1faa8edb5ae3 web/facet.py
--- a/web/facet.py	Wed Oct 12 19:06:22 2011 +0200
+++ b/web/facet.py	Thu Oct 13 09:44:14 2011 +0200
@@ -90,6 +90,31 @@
 ## rqlst manipulation functions used by facets ################################
 
 def init_facets(rset, select, mainvar=None):
+    """Alters in place the <select> for filtering and returns related data.
+
+    Calls :func:`prepare_select` to prepare the syntaxtree for selection and
+    :func:`get_filtered_variable` that selects the variable to be filtered and
+    drops several parts of the select tree. See each function docstring for
+    details.
+
+    :param rset: ResultSet we init facet for.
+    :type rset: :class:`~cubicweb.rset.ResultSet`
+
+    :param select: Select statement to be *altered* to support filtering.
+    :type select:   :class:`~rql.stmts.Select` from the ``rset`` parameters.
+
+    :param mainvar: Name of the variable we want to filter with facets.
+    :type mainvar:  string
+
+    :rtype: (filtered_variable, baserql) tuple.
+    :return filtered_variable:  A rql class:`~rql.node.VariableRef`
+                                instance as returned by
+                                :func:`get_filtered_variable`.
+
+    :return baserql: A string containing the rql before
+                     :func:`prepare_select` but after
+                     :func:`get_filtered_variable`.
+    """
     rset.req.vreg.rqlhelper.annotate(select)
     filtered_variable = get_filtered_variable(select, mainvar)
     baserql = select.as_string(kwargs=rset.args) # before call to prepare_select