Add some documentation sugar for ``having`` criterion.

1 files changed, 15 insertions, 3 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 77d3cd2d3..103b0a795 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1231,7 +1231,7 @@ class Query(object):
     @_generative(_no_statement_condition, _no_limit_offset)
     def group_by(self, *criterion):
         """apply one or more GROUP BY criterion to the query and return 
-        the newly resulting ``Query``"""
+        the newly resulting :class:`.Query`"""
 
         criterion = list(chain(*[_orm_columns(c) for c in criterion]))
 
@@ -1244,8 +1244,20 @@ class Query(object):
 
     @_generative(_no_statement_condition, _no_limit_offset)
     def having(self, criterion):
-        """apply a HAVING criterion to the query and return the 
-        newly resulting ``Query``."""
+        """apply a HAVING criterion to the query and return the
+        newly resulting :class:`.Query`.
+        
+        :meth:`having` is used in conjunction with :meth:`group_by`.
+ 
+        HAVING criterion makes it possible to use filters on aggregate
+        functions like COUNT, SUM, AVG, MAX, and MIN, eg.::
+ 
+            q = session.query(User.id).\\
+                        join(User.addresses).\\
+                        group_by(User.id).\\
+                        having(func.count(Address.id) > 2)
+ 
+        """
 
         if isinstance(criterion, basestring):
             criterion = sql.text(criterion)