javadoc: HTML 5 tags; package is on 1st line in java src (#16)

Author: adamdickmeiss

src/main/java/org/z3950/zing/cql/CQLAndNode.java

@@ -1,4 +1,3 @@
-
 package org.z3950.zing.cql;
 
 
@@ -10,6 +9,13 @@ public class CQLAndNode extends CQLBooleanNode {
     /**
      * Creates a new AND node with the specified left- and right-hand
      * sides and modifiers.
+     * @param left the left-hand side of the AND
+     * @param right the right-hand side of the AND
+     * @param ms the modifiers to apply to this AND
+     * @see ModifierSet
+     * @see CQLNode
+     * @see CQLBoolean
+     * @see CQLBooleanNode
      */
     public CQLAndNode(CQLNode left, CQLNode right, ModifierSet ms) {
 	super(left, right, ms, CQLBoolean.AND);

src/main/java/org/z3950/zing/cql/CQLBoolean.java

@@ -1,14 +1,16 @@
-/*
- * Copyright (c) 1995-2016, Index Data
- * All rights reserved.
- * See the file LICENSE for details.
- */
 package org.z3950.zing.cql;
 
 /**
- *
+ * Represents a boolean operator in CQL.
  * @author jakub
  */
 public enum CQLBoolean {
-  AND, OR, NOT, PROX;
+  /** AND is the same as CQL's "and" */
+  AND,
+  /** OR is the same as CQL's "or" */
+  OR,
+  /** NOT is the same as CQL's "not" */
+  NOT,
+  /** PROX is the same as CQL's "prox" */
+  PROX;
 }

src/main/java/org/z3950/zing/cql/CQLBooleanNode.java

@@ -1,5 +1,5 @@
-
 package org.z3950.zing.cql;
+
 import java.util.List;
 import java.util.Properties;
 
@@ -18,6 +18,7 @@ public CQLBoolean getOperator() {
 
     /**
      * The root of a parse-tree representing the left-hand side.
+     * @return the left operand of this boolean node
      */
     public CQLNode getLeftOperand() {
         return left;
@@ -27,6 +28,7 @@ public CQLNode getLeftOperand() {
 
     /**
      * The root of a parse-tree representing the right-hand side.
+     * @return the right operand of this boolean node
      */
     public CQLNode getRightOperand() {
         return right;
@@ -36,6 +38,7 @@ public CQLNode getRightOperand() {
 
     /**
      * The set of modifiers that are applied to this boolean.
+     * @return a list of Modifier objects, which may be empty.
      */
     public List<Modifier> getModifiers() {
         return ms.getModifiers();
@@ -57,7 +60,6 @@ public void traverse(CQLNodeVisitor visitor) {
       visitor.onBooleanNodeEnd(this);
     }
 
-
     @Override
     void toXCQLInternal(XCQLBuilder b, int level,
         List<CQLPrefix> prefixes, List<ModifierSet> sortkeys) {

src/main/java/org/z3950/zing/cql/CQLDefaultNodeVisitor.java

@@ -1,9 +1,3 @@
-/*
- * Copyright (c) 1995-2014, Index Data
- * All rights reserved.
- * See the file LICENSE for details.
- */
-
 package org.z3950.zing.cql;
 
 /**

src/main/java/org/z3950/zing/cql/CQLGenerator.java

@@ -1,24 +1,22 @@
-
 package org.z3950.zing.cql;
+
 import java.util.Properties;
 import java.util.Random;
 import java.io.InputStream;
 import java.io.FileInputStream;
-import java.io.FileNotFoundException;
-
 
 /**
  * A generator that produces random CQL queries.
  * <P>
  * Why is that useful?  Mainly to produce test-cases for CQL parsers
- * (including the <TT>CQLParser</TT> class in this package): you can
+ * (including the <code>CQLParser</code> class in this package): you can
  * generate a random search tree, render it to XCQL and remember the
  * result.  Then decompile the tree to CQL, feed the generated CQL to
  * the parser of your choice, and check that the XCQL it comes up with
  * is the same what you got from your initial rendering.
  * <P>
- * This code is based on the same grammar as the <TT>CQLParser</TT> class in
- * this distribution - there is a <TT>generate_<I>x</I>()</TT> method
+ * This code is based on the same grammar as the <code>CQLParser</code> class in
+ * this distribution - there is a <code>generate_<I>x</I>()</code> method
  * for each grammar element <I>X</I>.
  *
  * @see		<A href="http://zing.z3950.org/cql/index.html"
@@ -31,67 +29,61 @@ public class CQLGenerator {
 
     /**
      * Creates a new CQL generator with the specified parameters.
-     * <P>
      * @param params
-     *	A <TT>Properties</TT> table containing configuration
+     *	A <code>Properties</code> table containing configuration
      *	parameters for the queries to be generated by this generator.
-     *  Recognised parameters are:
      *  <P>
+     *  Recognised parameters are:
+     *  </P>
      *  <DL>
-     *	 <DT><TT>seed</TT></DT>
+     *	 <DT><code>seed</code></DT>
      *	 <DD>
-     *	  If specified, this is a <TT>long</TT> used to seed the
+     *	  If specified, this is a <code>long</code> used to seed the
      *	  random number generator, so that the CQL generator can be
      *	  run repeatably, giving the same results each time.  If it's
      *	  omitted, then no seed is explicitly specified, and the
      *	  results of each run will be different (so long as you don't
      *	  run it more that 2^32 times :-)
-     *	  <P>
      *   </DD>
-     *	 <DT><TT>complexQuery</TT></DT>
+     *	 <DT><code>complexQuery</code></DT>
      *	 <DD>
      *	  [mandatory] A floating-point number between 0.0 and 1.0,
-     *	  indicating the probability for each <TT>cql-query</TT> node
+     *	  indicating the probability for each <code>cql-query</code> node
      *	  that it will be expanded into a ``complex query''
-     *	  (<TT>cql-query&nbsp;boolean&nbsp;search-clause</TT>) rather
-     *	  than a <TT>search-clause</TT>.
-     *	  <P>
+     *	  (<code>cql-query&nbsp;boolean&nbsp;search-clause</code>) rather
+     *	  than a <code>search-clause</code>.
      *   </DD>
-     *	 <DT><TT>complexClause</TT></DT>
+     *	 <DT><code>complexClause</code></DT>
      *	 <DD>
      *	  [mandatory] A floating-point number between 0.0 and 1.0,
-     *	  indicating the probability for each <TT>search-clause</TT>
+     *	  indicating the probability for each <code>search-clause</code>
      *	  node that it will be expanded into a full sub-query rather
-     *	  than an <TT>[ index relation ] term</TT> triplet.
-     *	  <P>
+     *	  than an <code>[ index relation ] term</code> triplet.
      *   </DD>
-     *	 <DT><TT>proxOp</TT></DT>
+     *	 <DT><code>proxOp</code></DT>
      *	 <DD>
      *	  [mandatory] A floating-point number between 0.0 and 1.0,
      *	  indicating the probability that each boolean operator will
      *	  be chosen to be proximity operation; otherwise, the three
-     *	  simpler boolean operations (<TT>and</TT>, <TT>or</TT> and
-     *	  <TT>not</TT>) are chosen with equal probability.
-     *	  <P>
+     *	  simpler boolean operations (<code>and</code>, <code>or</code> and
+     *	  <code>not</code>) are chosen with equal probability.
      *   </DD>
-     *	 <DT><TT>equalsRelation</TT></DT>
+     *	 <DT><code>equalsRelation</code></DT>
      *	 <DD>
      *	  [mandatory] A floating-point number between 0.0 and 1.0,
      *	  indicating the probability that each relation will be chosen
-     *	  to be <TT>=</TT> - this is treated as a special case, since
+     *	  to be <code>=</code> - this is treated as a special case, since
      *	  it's likely to be by far the most common relation in
      *	  ``real life'' searches.
-     *	  <P>
      *   </DD>
-     *	 <DT><TT>numericRelation</TT></DT>
-     *	 <DD>
+     *	 <DT><code>numericRelation</code></DT>
+     *	 <DD>q
      *	  [mandatory] A floating-point number between 0.0 and 1.0,
      *	  indicating the probability that a relation, having chosen
-     *	  not to be <TT>=</TT>, is instead chosen to be one of the six
-     *	  numeric relations (<TT>&lt;</TT>, <TT>&gt;</TT>,
-     *	  <TT>&lt;=</TT>, <TT>&gt;=</TT>, <TT>&lt;&gt;</TT> and
-     *	  <TT>=</TT>).
-     *	  <P>
+     *	  not to be <code>=</code>, is instead chosen to be one of the six
+     *	  numeric relations (<code>&lt;</code>, <code>&gt;</code>,
+     *	  <code>&lt;=</code>, <code>&gt;=</code>, <code>&lt;&gt;</code> and
+     *	  <code>=</code>).
      *   </DD>
      *  </DL>
      */
@@ -116,11 +108,11 @@ private static void debug(String str) {
      * when it was created.  You are free to create as many random
      * queries as you wish from a single generator; each of them will
      * use the same parameters.
-     * <P>
+     * </P>
      * @return
-     *	A <TT>CQLNode</TT> that is the root of the generated tree.
-     *	That tree may be rendered in XCQL using its <TT>toXCQL()</TT>
-     *	method, or decompiled into CQL using its <TT>toCQL</TT>
+     *	A <code>CQLNode</code> that is the root of the generated tree.
+     *	That tree may be rendered in XCQL using its <code>toXCQL()</code>
+     *	method, or decompiled into CQL using its <code>toCQL</code>
      *	method.
      */
     public CQLNode generate() throws MissingParameterException {
@@ -264,9 +256,9 @@ boolean maybe(String param) throws MissingParameterException {
      * decompiles it into CQL which is written to standard output.
      * <P>
      * For example,
-     * <TT>java org.z3950.zing.cql.CQLGenerator
-     *	etc/generate.properties seed 18398</TT>,
-     * where the file <TT>generate.properties</TT> contains:<PRE>
+     * <code>java org.z3950.zing.cql.CQLGenerator
+     *	etc/generate.properties seed 18398</code>,
+     * where the file <code>generate.properties</code> contains:<PRE>
      *	complexQuery=0.4
      *	complexClause=0.4
      *	equalsRelation=0.5

src/main/java/org/z3950/zing/cql/CQLLexer.java

@@ -1,8 +1,3 @@
-/*
- * Copyright (c) 1995-2014, Index Datassss
- * All rights reserved.
- * See the file LICENSE for details.
- */
 package org.z3950.zing.cql;
 
 import java.io.BufferedReader;

src/main/java/org/z3950/zing/cql/CQLNode.java

@@ -1,12 +1,10 @@
-
 package org.z3950.zing.cql;
+
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Properties;
 
-
-
 /**
  * Represents a node in a CQL parse-tree.
  *
@@ -29,7 +27,6 @@ public String getResultSetName() {
 
     /**
      * Translates a parse-tree into an XCQL document.
-     * <P>
      * @return
      *	A String containing an XCQL document equivalent to the
      *	parse-tree whose root is this node.
@@ -79,7 +76,6 @@ static void renderSortKeys(XCQLBuilder b, int level,
 
     /**
      * Decompiles a parse-tree into a CQL query.
-     * <P>
      * @return
      *	A String containing a CQL query equivalent to the parse-tree
      *	whose root is this node, so that compiling that query will
@@ -96,17 +92,20 @@ static void renderSortKeys(XCQLBuilder b, int level,
      * <A href="http://indexdata.dk/yaz/doc/tools.php#PQF"
      *	>Chapter 7 (Supporting Tools)</A> of the
      * <A href="http://indexdata.dk/yaz/">YAZ</A> manual.
-     * <P>
      * @param config
-     *	A <TT>Properties</TT> object containing configuration
+     *	A <code>Properties</code> object containing configuration
      *	information that specifies the mapping from CQL indexes,
      *	relations, etc. to Type-1 attributes.  The mapping
      *	specification is described in the CQL-Java distribution's
      *	sample PQF-mapping configuration file,
-     *	<TT>etc/pqf.properties</TT>, which see.
+     *	<code>etc/pqf.properties</code>, which see.
      * @return
      *	A String containing a PQF query equivalent to the parse-tree
      *	whose root is this node.
+     * @throws PQFTranslationException
+     *  If the parse-tree cannot be translated into PQF, for example
+     *  because it contains a CQL relation that is not supported by the
+     *  PQF configuration.
      */
     abstract public String toPQF(Properties config)
 	throws PQFTranslationException;
@@ -118,17 +117,21 @@ abstract public String toPQF(Properties config)
      * primarily for SRW-to-Z39.50 gateways.
      *
      * @param config
-     *	A <TT>Properties</TT> object containing configuration
+     *	A <code>Properties</code> object containing configuration
      *	information that specifies the mapping from CQL indexes,
      *	relations, etc. to Type-1 attributes.  The mapping
      *	specification is described in the CQL-Java distribution's
      *	sample PQF-mapping configuration file,
-     *	<TT>etc/pqf.properties</TT>, which see.
+     *	<code>etc/pqf.properties</code>, which see.
      * @return
      *	A byte array containing the BER packet.
      * @see
      *	<A href="ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc"
      *	        >ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc</A>
+     * @throws PQFTranslationException
+     *  If the parse-tree cannot be translated into PQF, for example
+     *  because it contains a CQL relation that is not supported by the
+     *  PQF configuration.
      */
     abstract public byte[] toType1BER(Properties config)
 	throws PQFTranslationException;

src/main/java/org/z3950/zing/cql/CQLNodeVisitor.java

@@ -1,9 +1,3 @@
-/*
- * Copyright (c) 1995-2014, Index Data
- * All rights reserved.
- * See the file LICENSE for details.
- */
-
 package org.z3950.zing.cql;
 
 /**

src/main/java/org/z3950/zing/cql/CQLNotNode.java

@@ -1,7 +1,5 @@
-
 package org.z3950.zing.cql;
 
-
 /**
  * Represents a NOT node in a CQL parse-tree.
  *

src/main/java/org/z3950/zing/cql/CQLOrNode.java

@@ -1,7 +1,5 @@
-
 package org.z3950.zing.cql;
 
-
 /**
  * Represents an OR node in a CQL parse-tree.
  *