fix #366 - Clean up code to pass linter and remove -Xdoclint:none from pom.xml

(cherry picked from commit 3601df7)

Author: sammefford

pom.xml

@@ -188,20 +188,6 @@
         </plugin>
 		</plugins>
 	</build>
-	<profiles>
-		<profile>
-			<id>Java 8</id>
-			<activation>
-				<jdk>1.8</jdk>
-			</activation>
-			<properties>
-				<!-- Disable Java 8 overly strict javadoc linter when building with Java 8
-					http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
-					-->
-				<additionalparam>-Xdoclint:none</additionalparam>
-			</properties>
-		</profile>
-	</profiles>
 	<dependencies>
 		<!-- direct build / run dependencies -->
         <!--

src/main/java/com/marklogic/client/admin/QueryOptionsManager.java

@@ -51,7 +51,7 @@ public <T> T optionsListAs(Format format, Class<T> as)
      * By default, standard Java IO classes for document content are registered.
      * 
      * @param listHandle a handle for reading the list of name options
-     * @param the type of QueryOptionsListReadHandle to return
+     * @param <T> the type of QueryOptionsListReadHandle to return
      * @return the handle populated with the names
      */
     public <T extends QueryOptionsListReadHandle> T optionsList(T listHandle)
@@ -75,7 +75,7 @@ public <T> T readOptionsAs(String name, Format format, Class<T> as)
 	 * 
 	 * @param name the name of options configuration stored on MarkLogic REST instance.
 	 * @param queryOptionsHandle an object into which to fetch the query options.
-	 * @param the type of QueryOptionsListReadHandle to return
+	 * @param <T> the type of QueryOptionsListReadHandle to return
 	 * @return an object holding the query configurations
 	 */
     public <T extends QueryOptionsReadHandle> T readOptions(String name, T queryOptionsHandle)

src/main/java/com/marklogic/client/admin/TransformExtensionsManager.java

@@ -69,6 +69,7 @@ public interface TransformExtensionsManager {
 	/**
 	 * Lists the installed transform extensions.
 	 * @param listHandle	a handle on a JSON or XML representation of the list
+	 * @param <T> the type of StructureReadHandle to return
 	 * @return	the list handle
 	 */
 	public <T extends StructureReadHandle> T listTransforms(T listHandle)

src/main/java/com/marklogic/client/document/DocumentManager.java

@@ -388,6 +388,7 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
      * @param contentHandle	a handle for reading the content of the document
      * @param transform	a server transform to modify the document content
      * @param transaction	a open transaction under which the document may have been created or deleted
+     * @param <T> the type of content handle to return
      * @return	the content handle populated with the content of the document in the database
      */
     public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform, Transaction transaction)
@@ -1112,6 +1113,7 @@ public void patchAs(String docId, Object patch)
      * 
      * @param docId	the URI identifier for the document
      * @param metadataHandle	a handle for reading the metadata of the document
+     * @param <T> the type of DocumentMetadataReadHandle to return
      * @return	the metadata handle populated with the metadata for the document in the database
      */
     public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T metadataHandle)
@@ -1124,6 +1126,7 @@ public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T met
      * @param docId	the URI identifier for the document
      * @param metadataHandle	a handle for reading the metadata of the document
      * @param transaction	a open transaction under which the document may have been created or deleted
+     * @param <T> the type of DocumentMetadataReadHandle to return
      * @return	the metadata handle populated with the metadata for the document in the database
      */
     public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T metadataHandle, Transaction transaction)

src/main/java/com/marklogic/client/document/DocumentPage.java

@@ -37,7 +37,11 @@
  * you must call close() to free the underlying resources.
  */
 public interface DocumentPage extends Page<DocumentRecord>, Closeable {
-    /** Convenience method combines the functionality of Page.next() and DocumentRecord.getContent(). */
+    /** Convenience method combines the functionality of Page.next() and DocumentRecord.getContent().
+     * @param contentHandle the handle top populate with the contents from the next document
+     * @param <T> the type of AbstractReadHandle to return
+     * @return the contents of the next document
+     */
     public <T extends AbstractReadHandle> T nextContent(T contentHandle);
     /** Frees the underlying resources, including the http connection. */
     public void close();

src/main/java/com/marklogic/client/document/DocumentPatchBuilder.java

@@ -84,6 +84,8 @@ public String toString() {
 
 	/**
 	 * Specifies the language for this patch to use
+	 * @param pathLang the language (XPath or JSONPath)
+	 * @return	the patch builder (for convenient chaining)
 	 */
 	public DocumentPatchBuilder pathLanguage(PathLanguage pathLang);
 

src/main/java/com/marklogic/client/document/DocumentWriteSet.java

@@ -29,6 +29,7 @@
  */
 public interface DocumentWriteSet extends Set<DocumentWriteOperation> {
     /** Sets the default metadata for this write set for all documents added after this call
+     * @param metadataHandle the handle containing the metatdata to use as defaults
      * @return this instance (for method chaining)
      */
     public DocumentWriteSet addDefault(DocumentMetadataWriteHandle metadataHandle);

src/main/java/com/marklogic/client/pojo/PojoRepository.java

@@ -189,7 +189,7 @@ public long count(String[] collections, Transaction transaction)
      */
     public long count(PojoQueryDefinition query)
         throws ForbiddenUserException, FailedRequestException;
-  
+
     /** In the context of transaction, the number of documents of the type managed by
      * this PojoRepository persisted in the database which match the query
      * @param query the query which results much match (queries are run unfiltered by default)
@@ -201,8 +201,10 @@ public long count(PojoQueryDefinition query)
      */
     public long count(PojoQueryDefinition query, Transaction transaction)
         throws ForbiddenUserException, FailedRequestException;
-  
-    /** Deletes from the database the documents with the corresponding ids */
+
+    /** Deletes from the database the persisted pojo instances with the corresponding ids
+     * @param ids the ids for the pojo instances to delete from the server
+     */
     public void delete(ID... ids)
         throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
 

src/main/java/com/marklogic/client/query/MatchDocumentSummary.java

@@ -156,6 +156,7 @@ public interface MatchDocumentSummary {
 
     /**
      * Returns the format associated with this document
+     * @return the format
      */
     public Format getFormat();
 
@@ -169,6 +170,7 @@ public interface MatchDocumentSummary {
 	/**
      * Returns the relevance information for the result.
      * @param handle	An XML handle for reading the relevance information.
+     * @param <T> the type of XMLReadHandle to return
      * @return	The handle on the relevance information.
 	 */
 	public <T extends XMLReadHandle> T getRelevanceInfo(T handle);

src/main/java/com/marklogic/client/query/QueryManager.java

@@ -361,6 +361,7 @@ public enum QueryView {
      * @param valueHandle	a handle for reading the values for the matched documents
      * @param start	the offset of the first returned result (where 1 is the first value)
      * @param transaction	a open transaction for matching documents
+     * @param <T> the type of ValuesReadHandle to return
      * @return	the handle populated with the values from the index
      */
     public <T extends ValuesReadHandle> T values(ValuesDefinition valdef, T valueHandle, long start, Transaction transaction);
@@ -370,6 +371,7 @@ public enum QueryView {
      * based on query criteria and, potentially, previously saved query options.  
      * @param valdef	the definition of query criteria and query options
      * @param tupleHandle	a handle for reading the tuples for the matched documents
+     * @param <T> the type of TuplesReadHandle to return
      * @return	the handle populated with the tuples from the index
      */
     public <T extends TuplesReadHandle> T tuples(ValuesDefinition valdef, T tupleHandle);
@@ -380,6 +382,7 @@ public enum QueryView {
      * @param valdef	the definition of query criteria and query options
      * @param tupleHandle	a handle for reading the tuples for the matched documents
      * @param start	the offset of the first returned result (where 1 is the first tuple)
+     * @param <T> the type of TuplesReadHandle to return
      * @return	the handle populated with the tuples from the index
      */
     public <T extends TuplesReadHandle> T tuples(ValuesDefinition valdef, T tupleHandle, long start);
@@ -392,6 +395,7 @@ public enum QueryView {
      * @param valdef	the definition of query criteria and query options
      * @param tupleHandle	a handle for reading the tuples for the matched documents
      * @param transaction	a open transaction for matching documents
+     * @param <T> the type of TuplesReadHandle to return
      * @return	the handle populated with the tuples from the index
      */
     public <T extends TuplesReadHandle> T tuples(ValuesDefinition valdef, T tupleHandle, Transaction transaction);
@@ -405,6 +409,7 @@ public enum QueryView {
      * @param tupleHandle	a handle for reading the tuples for the matched documents
      * @param start	the offset of the first returned result (where 1 is the first tuple)
      * @param transaction	a open transaction for matching documents
+     * @param <T> the type of TuplesReadHandle to return
      * @return	the handle populated with the tuples from the index
      */
     public <T extends TuplesReadHandle> T tuples(ValuesDefinition valdef, T tupleHandle, long start, Transaction transaction);
@@ -414,6 +419,7 @@ public enum QueryView {
      * values list definition and, potentially, previously saved query options.
      * @param valdef the definition of the query criteria and options
      * @param valueHandle a handle for reading the list of names lexicon configurations
+     * @param <T> the type of ValuesListReadHandle to return
      * @return the handle populated with the names
      */
     public <T extends ValuesListReadHandle> T valuesList(ValuesListDefinition valdef, T valueHandle);
@@ -426,13 +432,15 @@ public enum QueryView {
      * @param valdef the definition of the query criteria and options
      * @param valueHandle a handle for reading the list of names lexicon configurations
      * @param transaction	a open transaction for matching documents
+     * @param <T> the type of ValuesListReadHandle to return
      * @return the handle populated with the names
      */
     public <T extends ValuesListReadHandle> T valuesList(ValuesListDefinition valdef, T valueHandle, Transaction transaction);
 
     /**
      * Retrieves the list of available named query options.
      * @param listHandle a handle for reading the list of name options
+     * @param <T> the type of QueryOptionsListReadHandle to return
      * @return the handle populated with the names
      */
     public <T extends QueryOptionsListReadHandle> T optionsList(T listHandle);
@@ -443,6 +451,7 @@ public enum QueryView {
      * options deleted by the transaction.
      * @param valueHandle a handle for reading the list of name options
      * @param transaction	a open transaction for matching documents
+     * @param <T> the type of QueryOptionsListReadHandle to return
      * @return the handle populated with the names
      */
     public <T extends QueryOptionsListReadHandle> T optionsList(T valueHandle, Transaction transaction);
@@ -471,17 +480,19 @@ public enum QueryView {
     public MatchDocumentSummary findOne(QueryDefinition querydef, Transaction transaction);
 
 	/**
-     * Converts a query by example into a combined query that expresses the criteria
-     * as a structured search.
+     * Sends a query by example to the server to convert into a combined query
+     * that expresses the criteria as a structured search.
      * @param query	the query by example
-     * @param convertedHandle
+     * @param convertedHandle the container to use for the new converted query
+     * @param <T> the type of StructureReadHandle to return
      * @return	the handle populated with the combined query
      */
     public <T extends StructureReadHandle> T convert(RawQueryByExampleDefinition query, T convertedHandle);
     /**
      * Checks a query by example for mistakes in expressing the criteria.
      * @param query	the query by example
      * @param reportHandle	a handle for reading the validation report 
+     * @param <T> the type of StructureReadHandle to return
      * @return	the handle populated with the validation report
      */
     public <T extends StructureReadHandle> T validate(RawQueryByExampleDefinition query, T reportHandle);