work on #366 - fix all complaints from the Java 8 linter so we can build javadocs with no warnings

(cherry picked from commit 00bb9af)

Author: sammefford

src/main/java/com/marklogic/client/DatabaseClient.java

@@ -119,10 +119,14 @@ public interface DatabaseClient {
      */
     public ServerConfigurationManager newServerConfigManager();
 
-    /** Creates a manager for CRUD operations on semantic graphs.  */
+    /** Creates a manager for CRUD operations on semantic graphs.
+     * @return the new GraphManager instance
+     */
     public GraphManager newGraphManager();
 
-    /** Creates a manager for executing SPARQL queries and retrieving results. */
+    /** Creates a manager for executing SPARQL queries and retrieving results.
+     * @return the new SPARQLQueryManager instance
+     */
     public SPARQLQueryManager newSPARQLQueryManager();
 
     /**
@@ -134,6 +138,8 @@ public interface DatabaseClient {
      * @param clazz the class type for this PojoRepository to handle
      * @param idClass the class type of the id field for this clazz, must obviously 
      *          be Serializable or we'll struggle to marshall it
+     * @param <T> the pojo type this PojoRepository will manage
+     * @param <ID> the scalar type of the id for pojos of type &lt;T&gt;
      * @return the initialized PojoRepository
      **/
     public <T, ID extends Serializable> PojoRepository<T, ID> newPojoRepository(Class<T> clazz, Class<ID> idClass);
@@ -143,6 +149,7 @@ public interface DatabaseClient {
      * 
      * @param resourceName	the name of the extension resource
      * @param resourceManager	the manager for the extension resource
+     * @param <T> the type of ResourceManager to init for the extension resource
      * @return	the initialized resource manager
      */
     public <T extends ResourceManager> T init(String resourceName, T resourceManager);
@@ -186,6 +193,7 @@ public interface DatabaseClient {
      * xdbc:invoke privilege.  If this DatabaseClient is pointed at a database different
      * than the default for this REST server, you will need the xdbc:eval-in or xdbc:invoke-in
      * privilege.
+     * @return the new ServerEvaluationCall instance
      */
     public ServerEvaluationCall newServerEval();
 

src/main/java/com/marklogic/client/DatabaseClientFactory.java

@@ -95,6 +95,7 @@ public interface SSLHostnameVerifier {
 		 * @param hostname	the name of the checked host
 		 * @param cns	common names for the checked host
 		 * @param subjectAlts	alternative subject names for the checked host
+		 * @throws SSLException if the hostname isn't acceptable
 		 */
 		public void verify(String hostname, String[] cns, String[] subjectAlts) throws SSLException;
 
@@ -165,6 +166,7 @@ public interface HandleFactoryRegistry {
 		 * Creates a ContentHandle if the registry has a factory
 		 * for the class of the IO representation.
 		 * @param type	the class for an IO representation
+		 * @param <C> the registered type for the returned handle
 		 * @return	a content handle or null if no factory supports the class
 		 */
 		public <C> ContentHandle<C> makeHandle(Class<C> type);

src/main/java/com/marklogic/client/MarkLogicServerException.java

@@ -33,8 +33,8 @@ public abstract class MarkLogicServerException extends RuntimeException {
 	private FailedRequest failedRequest;
 
 	/**
-	 * @param localMessage
-	 * @param failedRequest
+	 * @param localMessage message describing the exception
+	 * @param failedRequest details about the failed request behind this exception
 	 */
 	public MarkLogicServerException(String localMessage, FailedRequest failedRequest) {
 		super(localMessage);

src/main/java/com/marklogic/client/Transaction.java

@@ -55,6 +55,7 @@ public interface Transaction {
 	 * Reads the status for the transaction including whether the transaction
 	 * has timed out.
 	 * @param handle	a JSON or XML handle on the content of the status report
+   * @param <T> the type of StructureReadHandle handle to return
 	 * @return	the status report handle
 	 */
 	public <T extends StructureReadHandle> T readStatus(T handle) throws ForbiddenUserException, FailedRequestException;

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

@@ -51,6 +51,7 @@ public ExtensionLibraryDescriptor[] list(String directory)
 	 * 
 	 * @param libraryPath the path to the library
 	 * @param as	the IO class for reading the library asset
+	 * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the library asset 
 	 */
 	public <T> T readAs(String libraryPath, Class<T> as)
@@ -63,6 +64,7 @@ public <T> T readAs(String libraryPath, Class<T> as)
 	 * 
 	 * @param  libraryDescriptor a descriptor that locates the library
 	 * @param as	the IO class for reading the library asset
+	 * @param <T> the type of AbstractReadHandle to return
 	 * @return	an object of the IO class with the library asset 
 	 */
 	public <T> T read(ExtensionLibraryDescriptor libraryDescriptor, Class<T> as)
@@ -72,6 +74,7 @@ public <T> T read(ExtensionLibraryDescriptor libraryDescriptor, Class<T> as)
 	 * Reads the contents of a library asset into a handle.
 	 * @param libraryPath the path to the library
 	 * @param readHandle a handle for reading the contents of the file
+	 * @param <T> the type of AbstractReadHandle to return
 	 * @return the handle for the library asset
 	 */
 	public <T extends AbstractReadHandle> T read(String libraryPath, T readHandle)
@@ -80,6 +83,7 @@ public <T extends AbstractReadHandle> T read(String libraryPath, T readHandle)
 	 * Reads the contents of a library asset into a handle.
 	 * @param  libraryDescriptor a descriptor that locates the library.
 	 * @param readHandle A handle for reading the contents of the file.
+	 * @param <T> the type of AbstractReadHandle to return
 	 * @return The handle.
 	 */
 	public <T extends AbstractReadHandle> T read(ExtensionLibraryDescriptor libraryDescriptor, T readHandle)

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

@@ -57,7 +57,7 @@ public String getCapability() {
 		}
 		/**
 		 * sets the capability for this permission
-		 * @param capability
+		 * @param capability the capability for this permission
 		 */
 		public void setCapability(String capability) {
 			this.capability = capability;

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

@@ -113,6 +113,7 @@ public void setVersion(String version) {
 	/**
 	 * Returns the script language for this resource extension, either XQUERY (default)
 	 * or JAVASCRIPT.
+	 * @return the script language for this resource extension
 	 */
     public ScriptLanguage getScriptLanguage() {
         return scriptLanguage;
@@ -121,6 +122,7 @@ public ScriptLanguage getScriptLanguage() {
 	/**
 	 * Specifies the script language for this resource extension, either XQUERY (default)
 	 * or JAVASCRIPT.
+	 * @param scriptLanguage the script language for this resource extension
 	 */
     public void setScriptLanguage(ScriptLanguage scriptLanguage) {
         this.scriptLanguage = scriptLanguage;

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

@@ -38,6 +38,7 @@ public interface QueryOptionsManager {
      * 
      * @param format	whether to provide the list in a JSON or XML representation
      * @param as	the IO class for reading the list of options
+     * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the option names
      */
 	public <T> T optionsListAs(Format format, Class<T> as)
@@ -50,6 +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
      * @return the handle populated with the names
      */
     public <T extends QueryOptionsListReadHandle> T optionsList(T listHandle)
@@ -61,6 +63,7 @@ public <T extends QueryOptionsListReadHandle> T optionsList(T listHandle)
 	 * @param name the name of options configuration stored on MarkLogic REST instance.
      * @param format	whether to provide the options in a JSON or XML representation
      * @param as	the IO class for reading the query options
+   * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return an object of the IO class with the query options
      */
 	public <T> T readOptionsAs(String name, Format format, Class<T> as)
@@ -72,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 <T> a set of classes able to read query configurations from the database.
+	 * @param 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/ResourceExtensionsManager.java

@@ -39,6 +39,7 @@ public interface ResourceExtensionsManager {
      * 
      * @param format	whether to provide the list in a JSON or XML representation
      * @param as	the IO class for reading the list of resource service extensions
+     * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the list of resource service extensions
      */
     public <T> T listServicesAs(Format format, Class<T> as);
@@ -52,12 +53,14 @@ public interface ResourceExtensionsManager {
      * @param format	whether to provide the list in a JSON or XML representation
      * @param as	the IO class for reading the list of resource service extensions
      * @param refresh	whether to parse metadata from the extension source
+     * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the list of resource service extensions
      */
     public <T> T listServicesAs(Format format, Class<T> as, boolean refresh);
     /**
 	 * Reads the list of resource service extensions installed on the server.
 	 * @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 listServices(T listHandle);
@@ -67,6 +70,7 @@ public interface ResourceExtensionsManager {
 	 * the extension source.
 	 * @param listHandle	a handle on a JSON or XML representation of the list
      * @param refresh	whether to parse metadata from the extension source
+	 * @param <T> the type of StructureReadHandle to return
 	 * @return	the list handle
      */
     public <T extends StructureReadHandle> T listServices(T listHandle, boolean refresh);
@@ -80,6 +84,7 @@ public interface ResourceExtensionsManager {
      * 
      * @param resourceName	the name of the resource
      * @param as	the IO class for reading the source code as text
+     * @param <T> the type of object that will be returned by the handle registered for it
      * @return	an object of the IO class with the source code for the service
      */
     public <T> T readServicesAs(String resourceName, Class<T> as);
@@ -88,6 +93,7 @@ public interface ResourceExtensionsManager {
      * Reads the XQuery implementation of the services for a resource.
      * @param resourceName	the name of the resource
      * @param sourceHandle	a handle for reading the text of the XQuery implementation.
+     * @param <T> the type of TextReadHandle to return
      * @return	the XQuery source code
      */
     public <T extends TextReadHandle> T readServices(String resourceName, T sourceHandle);

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

@@ -47,6 +47,7 @@ public interface TransformExtensionsManager {
      * 
      * @param format	whether to provide the list in a JSON or XML representation
      * @param as	the IO class for reading the list of transform extensions
+     * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the list of transform extensions
      */
     public <T> T listTransformsAs(Format format, Class<T> as);
@@ -60,6 +61,7 @@ public interface TransformExtensionsManager {
      * @param format	whether to provide the list in a JSON or XML representation
      * @param as	the IO class for reading the list of transform extensions
      * @param refresh	whether to parse metadata from the extension source
+     * @param <T> the type of object that will be returned by the handle registered for it
 	 * @return	an object of the IO class with the list of transform extensions
      */
     public <T> T listTransformsAs(Format format, Class<T> as, boolean refresh);
@@ -76,6 +78,7 @@ public <T extends StructureReadHandle> T listTransforms(T listHandle)
 	 * the metadata about each extension by parsing the extension source.
 	 * @param listHandle	a handle on a JSON or XML representation of the list
      * @param refresh	whether to parse metadata from the extension source
+	 * @param <T> the type of StructureReadHandle to return
 	 * @return	the list handle
 	 */
 	public <T extends StructureReadHandle> T listTransforms(T listHandle, boolean refresh)
@@ -90,6 +93,7 @@ public <T extends StructureReadHandle> T listTransforms(T listHandle, boolean re
      * 
      * @param transformName	the name of the transform
      * @param as	the IO class for reading the source code as XML
+     * @param <T> the type of object that will be returned by the handle registered for it
      * @return	an object of the IO class with the XSLT source code
 	 */
 	public <T> T readXSLTransformAs(String transformName, Class<T> as)
@@ -99,6 +103,7 @@ public <T> T readXSLTransformAs(String transformName, Class<T> as)
      * Reads the source for a transform implemented in XSLT.
      * @param transformName	the name of the transform
      * @param sourceHandle	a handle for reading the text of the XSLT implementation.
+     * @param <T> the type of XMLReadHandle to return
      * @return	the XSLT source code
 	 */
     public <T extends XMLReadHandle> T readXSLTransform(String transformName, T sourceHandle)
@@ -113,6 +118,7 @@ public <T extends XMLReadHandle> T readXSLTransform(String transformName, T sour
      * 
      * @param transformName	the name of the transform
      * @param as	the IO class for reading the source code as text
+     * @param <T> the type of object that will be returned by the handle registered for it
      * @return	an object of the IO class with the XQuery source code
      */
 	public <T> T readXQueryTransformAs(String transformName, Class<T> as)
@@ -122,6 +128,7 @@ public <T> T readXQueryTransformAs(String transformName, Class<T> as)
      * Reads the source for a transform implemented in XQuery.
      * @param transformName	the name of the transform
      * @param sourceHandle	a handle for reading the text of the XQuery implementation.
+     * @param <T> the type of TextReadHandle to return
      * @return	the XQuery source code
 	 */
 	public <T extends TextReadHandle> T readXQueryTransform(String transformName, T sourceHandle)
@@ -136,6 +143,7 @@ public <T extends TextReadHandle> T readXQueryTransform(String transformName, T
    * 
    * @param transformName	the name of the transform
    * @param as	the IO class for reading the source code as text
+   * @param <T> the type of object that will be returned by the handle registered for it
    * @return	an object of the IO class with the Javascript source code
    */
 public <T> T readJavascriptTransformAs(String transformName, Class<T> as)
@@ -145,6 +153,7 @@ public <T> T readJavascriptTransformAs(String transformName, Class<T> as)
    * Reads the source for a transform implemented in Javascript.
    * @param transformName	the name of the transform
    * @param sourceHandle	a handle for reading the text of the Javascript implementation.
+   * @param <T> the type of TextReadHandle to return
    * @return	the Javascript source code
  */
 public <T extends TextReadHandle> T readJavascriptTransform(String transformName, T sourceHandle)