bug:19086 Javadoc improvements

cgreer · cgreer · commit cf1a94ff4d11 · 2012-08-24T23:23:16.000Z
git-svn-id: svn+ssh://svn.marklogic.com/project/engsvn/client-api/java/trunk@113055 62cac252-8da6-4816-9e9d-6dc37b19578c
diff --git a/src/main/java/com/marklogic/client/admin/config/QueryOptionsBuilder.java b/src/main/java/com/marklogic/client/admin/config/QueryOptionsBuilder.java
diff --git a/src/main/java/com/marklogic/client/admin/config/support/Annotatable.java b/src/main/java/com/marklogic/client/admin/config/support/Annotatable.java
@@ -20,7 +20,8 @@
 import com.marklogic.client.admin.config.QueryOptions.QueryAnnotation;
 
 /**
- * Provides simple interface for adding annotations and retrieving them
+ * Defines methods for adding annotations and retrieving them
+ * from those option nodes that can be annotated.
  */
 public interface Annotatable<T> {
 	T annotate(String xmlAnnotation);
diff --git a/src/main/java/com/marklogic/client/admin/config/support/Buckets.java b/src/main/java/com/marklogic/client/admin/config/support/Buckets.java
@@ -15,4 +15,9 @@
  */
 package com.marklogic.client.admin.config.support;
 
+/**
+ * Marks {@link com.marklogic.client.admin.config.QueryOptions.QueryRange.Bucket} 
+ * and {@link com.marklogic.client.admin.config.QueryOptions.QueryRange.ComputedBucket} 
+ * as buckets for the purposes of {@link com.marklogic.client.admin.config.QueryOptions.QueryRange} configuration.
+ */
 public interface Buckets {}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/ConstraintSource.java b/src/main/java/com/marklogic/client/admin/config/support/ConstraintSource.java
@@ -15,8 +15,10 @@
  */
 package com.marklogic.client.admin.config.support;
 
-/*
- * rename the interface referring to constraint-type elements.
- * i.e. range|value|word|geospatial|properties|custom|collection
+/**
+ * Marks the options configurations that can back constraints.  
+ * Used in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions only. Maps to
+ * range|value|word|geospatial|properties|custom|collection
+ * elements in the backing XML.
  */
-public interface ConstraintSource  {}
+public interface ConstraintSource  {}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/GeospatialIndex.java b/src/main/java/com/marklogic/client/admin/config/support/GeospatialIndex.java
@@ -15,8 +15,10 @@
  */
 package com.marklogic.client.admin.config.support;
 
-/*
- * Marker for geospatial index.
- * geo-elem-pair|geo-attr|geo-elem
+/**
+ * Marker for geospatial index configurations.
+ * Maps to geo-elem-pair|geo-attr|geo-elem
+ * in the Search API options schema.
+ * Not actually in use.
  */
 public interface GeospatialIndex {}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/GeospatialIndexType.java b/src/main/java/com/marklogic/client/admin/config/support/GeospatialIndexType.java
@@ -15,6 +15,11 @@
  */
 package com.marklogic.client.admin.config.support;
 
+/**
+ * Used in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} to help construct configurations for geospatial indexes.
+ * Must match the encoding method for geospatial coordinates, wich can be stored as
+ * delimited values in a single element, or as values in pairs of elements or attributes.
+ */
 public enum GeospatialIndexType {
 
 	ELEMENT, ELEMENT_PAIR, ATTRIBUTE_PAIR;
diff --git a/src/main/java/com/marklogic/client/admin/config/support/GeospatialSpec.java b/src/main/java/com/marklogic/client/admin/config/support/GeospatialSpec.java
@@ -19,6 +19,14 @@
 
 import com.marklogic.client.admin.config.support.GeospatialIndexType;
 
+/**
+ * Defines an interface to the methods for storing
+ * geospatial values in MarkLogic indexes.
+ * Depending on the {@link com.marklogic.client.admin.config.support.GeospatialIndexType}, different
+ * methods will actually be used in order to build
+ * the geospatial configuration.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions.
+ */
 public interface GeospatialSpec {
 
 
diff --git a/src/main/java/com/marklogic/client/admin/config/support/HeatmapAndOptions.java b/src/main/java/com/marklogic/client/admin/config/support/HeatmapAndOptions.java
@@ -19,6 +19,12 @@
 
 import com.marklogic.client.admin.config.QueryOptions.Heatmap;
 
+/**
+ * Models an object that helps build heatmaps for use 
+ * in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} geospatial expressions.
+ * Do not use directly.   Build using
+ * {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.heatmap()
+ */
 public class HeatmapAndOptions {
 
 	private Heatmap heatmap;
diff --git a/src/main/java/com/marklogic/client/admin/config/support/IndexSpec.java b/src/main/java/com/marklogic/client/admin/config/support/IndexSpec.java
@@ -20,7 +20,10 @@
 import com.marklogic.client.admin.config.QueryOptions.PathIndex;
 
 /**
- * Supports building query configurations by encapsulating common index methods in one place.
+ * Defines methods for accessing index (or indexable) configuration elements.  
+ * Indexes in MarkLogic may be built on element names, path expressions, fields, and json keys.
+ * This interface simply defines shared methods among those MarkLogic entities that 
+ * back term sources and range sources.
  */
 public interface IndexSpec {
 	
diff --git a/src/main/java/com/marklogic/client/admin/config/support/IndexSpecImpl.java b/src/main/java/com/marklogic/client/admin/config/support/IndexSpecImpl.java
@@ -22,7 +22,10 @@
 import com.marklogic.client.admin.config.QueryOptions.MarkLogicQName;
 import com.marklogic.client.admin.config.QueryOptions.PathIndex;
 
-
+/**
+ * Implements accessors to index or index-like configurations.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions.
+ */
 public class IndexSpecImpl implements TermSpec {
 	public QName getAttribute() {
 		return attribute;
diff --git a/src/main/java/com/marklogic/client/admin/config/support/Indexed.java b/src/main/java/com/marklogic/client/admin/config/support/Indexed.java
@@ -23,7 +23,8 @@
 
 
 /**
- * Classes that can have indexes attached to them are marked with this interface.
+ * Marks classes that are backed by MarkLogic indexes.
+ * Used to support {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions.
  */
 public interface Indexed {
 
@@ -36,4 +37,4 @@ public interface Indexed {
 	void setJsonKey(JsonKey jsonKey);
 
 	void setPath(PathIndex path);
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/MetadataExtract.java b/src/main/java/com/marklogic/client/admin/config/support/MetadataExtract.java
@@ -17,9 +17,11 @@
 
 import com.marklogic.client.admin.config.QueryOptions.QueryExtractMetadata;
 
-/*
- * Marker for qname|constraint-value|json-key
+/**
+ * Marks classes that can be included in metadata extractions.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.extractMetadata(...) expressions to build
+ * {@link com.marklogic.client.admin.config.QueryOptions.QueryExtractMetadata} objects.
  */
 public interface MetadataExtract {
 	public void build(QueryExtractMetadata metadata);
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/QueryOptionsConfiguration.java b/src/main/java/com/marklogic/client/admin/config/support/QueryOptionsConfiguration.java
@@ -21,10 +21,12 @@
 import com.marklogic.client.admin.config.QueryOptions.FragmentScope;
 
 /**
- * Interface that wraps building configuration options for a QueryOptions
- * object. It consists of a bunch of getters in order to access state, and a
+ * Interface that wraps building configuration options for a 
+ * {@link com.marklogic.client.admin.config.QueryOptions}
+ * object. Consists of getters in order to access state, and a
  * range of fluent setters that are used to successively build up a
  * configuration.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.configure(...) expressions.
  */
 public class QueryOptionsConfiguration {
 	private Integer concurrencyLevel;
diff --git a/src/main/java/com/marklogic/client/admin/config/support/QueryUri.java b/src/main/java/com/marklogic/client/admin/config/support/QueryUri.java
@@ -18,6 +18,10 @@
 import com.marklogic.client.admin.config.QueryOptions.QueryTuples;
 import com.marklogic.client.admin.config.QueryOptions.QueryValues;
 
+/**
+ * A special marker for indicating that the source of
+ * tuples or values is the URI lexicon.
+ */
 public enum QueryUri implements TupleSource {
 
 	YES;
@@ -37,4 +41,4 @@ public void build(QueryTuples tuples) {
 }
 
 
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/RangeIndexType.java b/src/main/java/com/marklogic/client/admin/config/support/RangeIndexType.java
@@ -16,7 +16,10 @@
 package com.marklogic.client.admin.config.support;
 
 
-
+/**
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.*RangeIndex(...) methods
+ * to mark classes that are backed my range indexes.
+ */
 public class RangeIndexType implements Typed {
 	public String type;
 	private String collation;
@@ -32,4 +35,4 @@ public String getCollation() {
 	public String getType() {
 		return type;
 	}
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/RangeIndexed.java b/src/main/java/com/marklogic/client/admin/config/support/RangeIndexed.java
@@ -16,6 +16,10 @@
 package com.marklogic.client.admin.config.support;
 
 
+/**
+ * Marks classes that carry type and collation attributes.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions.
+ */
 public interface RangeIndexed extends Indexed {
 
 	void setType(String type);
diff --git a/src/main/java/com/marklogic/client/admin/config/support/RangeSpec.java b/src/main/java/com/marklogic/client/admin/config/support/RangeSpec.java
@@ -16,7 +16,11 @@
 package com.marklogic.client.admin.config.support;
 
 
-
+/**
+ * Marks classes and defines methods for configuring a
+ * range index description.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.*RangeIndex(...) expressions.
+ */
 public interface RangeSpec extends Typed, IndexSpec {
 	
 	public void setType(String type);
@@ -30,4 +34,4 @@ public interface RangeSpec extends Typed, IndexSpec {
 	public void build(RangeIndexed rangeIndexed);
 	
 
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/TermIndexed.java b/src/main/java/com/marklogic/client/admin/config/support/TermIndexed.java
@@ -16,7 +16,10 @@
 package com.marklogic.client.admin.config.support;
 
 
-
+/**
+ * Marks options that are backed by term lists.
+ * Included for symmetry but not actually in use.
+ */
 public interface TermIndexed extends Indexed, TermOptions {
 
 
diff --git a/src/main/java/com/marklogic/client/admin/config/support/TermOptions.java b/src/main/java/com/marklogic/client/admin/config/support/TermOptions.java
@@ -17,6 +17,12 @@
 
 import java.util.List;
 
+/**
+ * Marks classes and defined methods for options that
+ * have term options and weights assigned to them.
+ * Used indirectly in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} to construct
+ * {@link com.marklogic.client.admin.config.QueryOptions.QueryCustom} and {@link com.marklogic.client.admin.config.QueryOptions.QueryTerm}.
+ */
 public interface TermOptions {
 
 	public List<String> getTermOptions();
diff --git a/src/main/java/com/marklogic/client/admin/config/support/TermSource.java b/src/main/java/com/marklogic/client/admin/config/support/TermSource.java
@@ -17,6 +17,11 @@
 
 import java.util.List;
 
+/**
+ * Marks the classes that can back a {@link com.marklogic.client.admin.config.QueryOptions.QueryTerm}
+ * configuration for default searches.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.term(...)
+ */
 public interface TermSource {
 	public List<String> getTermOptions();
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/TermSpec.java b/src/main/java/com/marklogic/client/admin/config/support/TermSpec.java
@@ -16,8 +16,14 @@
 package com.marklogic.client.admin.config.support;
 
 
-
+/**
+ * Marks configurations that can back term constraints, 
+ * such as the word lexicon.
+ * Returned by {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.*TermIndex methods for use in
+ * constructing {@link com.marklogic.client.admin.config.QueryOptions.QueryValues} 
+ * and {@link com.marklogic.client.admin.config.QueryOptions.QueryTerm} configurations.
+ */
 public interface TermSpec extends IndexSpec {
 
 	
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/TupleSource.java b/src/main/java/com/marklogic/client/admin/config/support/TupleSource.java
@@ -18,8 +18,12 @@
 import com.marklogic.client.admin.config.QueryOptions.QueryTuples;
 import com.marklogic.client.admin.config.QueryOptions.QueryValues;
 
+/**
+ * Marks classes that can back tuples definitions.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.tuples(...) expressions.
+ */
 public interface TupleSource {
 
 	void build(QueryTuples tuples);
 	void build(QueryValues values);
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/Typed.java b/src/main/java/com/marklogic/client/admin/config/support/Typed.java
@@ -16,7 +16,11 @@
 package com.marklogic.client.admin.config.support;
 
 
+/**
+ * Marks classes that carry type and collation attributes.
+ * Used only in {@link com.marklogic.client.admin.config.QueryOptionsBuilder} expressions.
+ */
 public interface Typed {
 	public String getType();
 	public String getCollation();
-}
+}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/ValuesOrTuples.java b/src/main/java/com/marklogic/client/admin/config/support/ValuesOrTuples.java
@@ -15,4 +15,9 @@
  */
 package com.marklogic.client.admin.config.support;
 
+/**
+ * Marks classes that can comprise values or tuples
+ * definitions.
+ * Not in use.  See {@link com.marklogic.client.admin.config.support.TupleSource}.
+ */
 public interface ValuesOrTuples {}
diff --git a/src/main/java/com/marklogic/client/admin/config/support/package-info.java b/src/main/java/com/marklogic/client/admin/config/support/package-info.java
@@ -1,7 +1,3 @@
-/**
- * The package provides supporting classes for use with QueryOptions,
- * QueryOptionsHandle, and QueryOptionsBuilder.
- */
 /*
  * Copyright 2012 MarkLogic Corporation
  *
@@ -17,4 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Interfaces and classes used by {@link com.marklogic.client.admin.config.QueryOptionsBuilder},
+ * {@link com.marklogic.client.admin.config.QueryOptions}, 
+ * and {@link com.marklogic.client.io.QueryOptionsHandle}
+ * to comprise builder expressions and mark function arguments.
+ * 
+ * <p>
+ * It shouldn't be necessary to use any of the classes in this package
+ * in client applications, except to support builder expressions.
+ */
 package com.marklogic.client.admin.config.support;
diff --git a/src/main/java/com/marklogic/client/impl/GeospatialSpecImpl.java b/src/main/java/com/marklogic/client/impl/GeospatialSpecImpl.java
@@ -21,6 +21,10 @@
 
 import javax.xml.namespace.QName;
 
+/**
+ * Implements methods for referencing geospatial indexes.
+ * Used in QueryOptionsBuilder expression building.
+ */
 public class GeospatialSpecImpl extends IndexSpecImpl implements GeospatialSpec {
 
 	private GeospatialIndexType geospatialIndexType;
diff --git a/src/main/java/com/marklogic/client/io/QueryOptionsHandle.java b/src/main/java/com/marklogic/client/io/QueryOptionsHandle.java
@@ -97,7 +97,7 @@
  * 
  * <pre>handle.withConstraints(...).withTerm(...).withOperators(...)</pre>
  * 
- * <p>and constructed items from QueryOptionsBuilder.</p>
+ * <p>and constructed items from {@link com.marklogic.client.admin.config.QueryOptionsBuilder}.</p>
  * 
  */
 public final class QueryOptionsHandle
