add documentation about filters

hibernate-core/src/main/java/org/hibernate/Filter.java

@@ -18,6 +18,10 @@ import org.hibernate.engine.spi.FilterDefinition;
  * A filter may be defined using {@link org.hibernate.annotations.FilterDef}
  * and {@link org.hibernate.annotations.Filter}, and must be explicitly
  * enabled at runtime by calling {@link Session#enableFilter(String)}.
+ * <p>
+ * Every parameter of the filter must be set immediately after
+ * {@code enableFilter()} is called, and before any other operation of the
+ * session is invoked.
  *
  * @see org.hibernate.annotations.FilterDef
  * @see Session#enableFilter(String)

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -1160,6 +1160,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 
 	/**
 	 * Enable the named {@linkplain Filter filter} for this current session.
+	 * <p>
+	 * The returned {@link Filter} object must be used to bind arguments
+	 * to parameters of the filter, and every parameter must be set before
+	 * any other operation of this session is called.
 	 *
 	 * @param filterName the name of the filter to be enabled.
 	 *

hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java

@@ -50,6 +50,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <pre>
  * session.enableFilter("Current");
  * </pre>
+ * <p>
+ * A filter has no effect unless it is explicitly enabled.
  *
  * @author Matthew Inger
  * @author Emmanuel Bernard

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -170,6 +170,26 @@
  * {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices
  * advocated above.
  *
+ * <h3 id="filters">Filters</h3>
+ *
+ * Filters are an extremely powerful feature of Hibernate, allowing the definition of
+ * parameterized families of filtered "views" of the domain data. They're also easy
+ * to use, with the minor caveat that they require the developer to express filtering
+ * expressions in native SQL.
+ * <ul>
+ * <li>The {@link org.hibernate.annotations.FilterDef} annotation defines a named
+ *     filter, declares its parameters, and might specify a filtering expression
+ *     used by default. There should be exactly one of these annotations per filter
+ *     name.
+ * <li>The {@link org.hibernate.annotations.Filter} annotation is used to identify
+ *     which entities and associations are affected by the filter, and provide a
+ *     more specific filtering condition.
+ * </ul>
+ * <p>
+ * Note that a filter has no affect unless it is
+ * {@linkplain org.hibernate.Session#enableFilter(java.lang.String) enabled} in a
+ * particular session.
+ *
  * <h3 id="dialect-specific-sql">Dialect-specific native SQL</h3>
  *
  * Many annotations in this package allow the specification of native SQL expressions or

hibernate-core/src/main/javadoc/overview.html

@@ -37,9 +37,10 @@
     <li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
     <li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
     <li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
-    <li>{@link org.hibernate.Transaction} to control local transactions</li>
+    <li>{@link org.hibernate.Transaction} to control local transactions,</li>
     <li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
     <li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
+    <li>{@link org.hibernate.Filter} to manage filters,</li>
     <li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
         and</li>
     <li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>

release/src/release/javadoc/overview.html

@@ -37,9 +37,10 @@
     <li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
     <li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
     <li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
-    <li>{@link org.hibernate.Transaction} to control local transactions</li>
+    <li>{@link org.hibernate.Transaction} to control local transactions,</li>
     <li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
     <li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
+    <li>{@link org.hibernate.Filter} to manage filters,</li>
     <li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
         and</li>
     <li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>