Index: lucene/queryparser/src/java/org/apache/lucene/queryparser/surround/parser/QueryParser.jj
===================================================================
--- lucene/queryparser/src/java/org/apache/lucene/queryparser/surround/parser/QueryParser.jj	(revision 1336580)
+++ lucene/queryparser/src/java/org/apache/lucene/queryparser/surround/parser/QueryParser.jj	(working copy)
@@ -49,7 +49,27 @@
 
 /**
  * This class is generated by JavaCC.  The only method that clients should need
- * to call is {@link #parse}.
+ * to call is <a href="#parse">parse()</a>.
+ *
+
+ * <p>This parser generates queries that make use of position information
+ *   (Span queries). It provides positional operators (<code>w</code> and
+ *   <code>n</code>) that accept a numeric distance, as well as boolean
+ *   operators (<code>and</code>, <code>or</code>, and <code>not</code>,
+ *   wildcards (<code>*</code> and <code>?</code>), quoting (with
+ *   <code>"</code>), and boosting (via <code>^</code>).</p>
+
+ *  <p>The operators (W, N, AND, OR, NOT) can be expressed lower-cased or
+ *   upper-cased, and the non-unary operators (everything but NOT) support
+ *   both infix <code>(a AND b AND c)</code> and prefix <code>AND(a, b,
+ *   c)</code> notation. </p>
+ 
+ *  <p>The W and N operators express a positional relationship among their
+ *  operands.  N is ordered, and W is unordered.  The distance is 1 by
+ *  default, meaning the operands are adjacent, or may be provided as a
+ *  prefix from 2-99.  So, for example, 3W(a, b) means that terms a and b
+ *  must appear within three positions of each other, or in other words, up
+ *  to two terms may appear between a and b.  </p>
  */
 
 public class QueryParser {