Fixing some javadoc warnings, quieting down others

rjrudin · rjrudin · commit 4c11702afa09 · 2021-07-20T10:05:38.000-04:00
diff --git a/build.gradle b/build.gradle
@@ -60,6 +60,8 @@ task javadocJar(type: Jar, dependsOn: javadoc) {
 	from javadoc
 }
 javadoc.failOnError = false
+// Ignores warnings on params that don't have descriptions, which is a little too noisy
+javadoc.options.addStringOption('Xdoclint:none', '-quiet')
 
 artifacts {
 	archives javadocJar, sourcesJar
diff --git a/src/main/java/com/marklogic/client/ext/es/EntityServicesManager.java b/src/main/java/com/marklogic/client/ext/es/EntityServicesManager.java
@@ -26,7 +26,7 @@ public EntityServicesManager(DatabaseClient client) {
 	/**
 	 * @param moduleName      appended to the baseUri to determine the model definition URI
 	 * @param modelDefinition JSON or XML
-	 * @return
+	 * @return the URI of the loaded model
 	 */
 	public String loadModel(String moduleName, String modelDefinition) {
 		GenericDocumentManager mgr = client.newDocumentManager();
diff --git a/src/main/java/com/marklogic/client/ext/file/AbstractDocumentFileReader.java b/src/main/java/com/marklogic/client/ext/file/AbstractDocumentFileReader.java
@@ -20,11 +20,9 @@ protected AbstractDocumentFileReader() {
 	}
 
 	/**
-	 * Retrieves a DocumentFileProcessor with the given short class name. Useful for when you want to customize a
-	 * particular processor.
-	 *
 	 * @param classShortName
-	 * @return
+	 * @return Retrieves a DocumentFileProcessor with the given short class name. Useful for when you want to customize a
+	 * particular processor.
 	 */
 	public DocumentFileProcessor getDocumentFileProcessor(String classShortName) {
 		for (DocumentFileProcessor processor : documentFileProcessors) {
@@ -47,7 +45,7 @@ public void addDocumentFileProcessor(DocumentFileProcessor processor) {
 	 * in 3.11.0, it defaults to false, as an exception typically indicates that the processing should stop.
 	 *
 	 * @param documentFile
-	 * @return
+	 * @return the result of processing the given DocumentFile; may return null
 	 */
 	protected DocumentFile processDocumentFile(DocumentFile documentFile) {
 		for (DocumentFileProcessor processor : documentFileProcessors) {
diff --git a/src/main/java/com/marklogic/client/ext/file/DefaultDocumentFileReader.java b/src/main/java/com/marklogic/client/ext/file/DefaultDocumentFileReader.java
@@ -37,7 +37,7 @@ public DefaultDocumentFileReader() {
 	 * DocumentFile that is constructed by a File.
 	 *
 	 * @param paths
-	 * @return
+	 * @return list of DocumentFile objects in the given paths
 	 */
 	public List<DocumentFile> readDocumentFiles(String... paths) {
 		documentFiles = new ArrayList<>();
@@ -67,7 +67,7 @@ public List<DocumentFile> readDocumentFiles(String... paths) {
 	 * will try to resolve the path from its daemon directory.
 	 *
 	 * @param path
-	 * @return
+	 * @return a Path object based on the given string path
 	 */
 	protected Path constructPath(String path) {
 		File f;
@@ -128,11 +128,9 @@ public FileVisitResult visitFile(Path path, BasicFileAttributes attrs) throws IO
 	}
 
 	/**
-	 * If any of the configured FileFilter objects do not accept the Path, then it is not accepted.
-	 *
 	 * @param path
 	 * @param attrs
-	 * @return
+	 * @return false if any of the configured FileFilter objects do not accept the Path, else true
 	 */
 	protected boolean acceptPath(Path path, BasicFileAttributes attrs) {
 		if (fileFilters != null) {
diff --git a/src/main/java/com/marklogic/client/ext/file/GenericFileLoader.java b/src/main/java/com/marklogic/client/ext/file/GenericFileLoader.java
@@ -68,7 +68,7 @@ public GenericFileLoader(BatchWriter batchWriter) {
 	 * If a DocumentFileReader has not been set yet, then one will be constructed before any files are read.
 	 *
 	 * @param paths
-	 * @return
+	 * @return list of files from the given paths
 	 */
 	public List<DocumentFile> loadFiles(String... paths) {
 		batchWriter.initialize();
@@ -199,9 +199,7 @@ protected void applyTokenReplacerOnKnownDocumentProcessors(AbstractDocumentFileR
 	}
 
 	/**
-	 * Builds a set of DocumentFileProcessor objects based on how this class has been configured.
-	 *
-	 * @return
+	 * @return a set of DocumentFileProcessor objects based on how this class has been configured.
 	 */
 	protected List<DocumentFileProcessor> buildDocumentFileProcessors() {
 		List<DocumentFileProcessor> processors = new ArrayList<>();
diff --git a/src/main/java/com/marklogic/client/ext/file/JarDocumentFileReader.java b/src/main/java/com/marklogic/client/ext/file/JarDocumentFileReader.java
@@ -49,7 +49,7 @@ public List<DocumentFile> readDocumentFiles(String... paths) {
 	 *
 	 * @param basePath
 	 * @param paths
-	 * @return
+	 * @return list of resources
 	 */
 	protected List<Resource> findResources(String basePath, String... paths) {
 		List<Resource> list = new ArrayList<>();
@@ -77,10 +77,8 @@ protected List<Resource> findResources(String basePath, String... paths) {
 	}
 
 	/**
-	 * Uses the list of FilenameFilter objects to determine if a document can be read from the given resource.
-	 *
 	 * @param r
-	 * @return
+	 * @return true if a document can be read from the given resource based on the list of FilenameFilter objects
 	 */
 	protected boolean canReadResource(Resource r) {
 		if (r == null) {
diff --git a/src/main/java/com/marklogic/client/ext/file/PropertiesDrivenDocumentFileProcessor.java b/src/main/java/com/marklogic/client/ext/file/PropertiesDrivenDocumentFileProcessor.java
@@ -37,7 +37,7 @@ public boolean accept(File file) {
 
 	/**
 	 * @param documentFile
-	 * @return
+	 * @return null if the file is not accepted, else the incoming DocumentFile
 	 */
 	@Override
 	public DocumentFile processDocumentFile(DocumentFile documentFile) {
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/ModulesLoader.java b/src/main/java/com/marklogic/client/ext/modulesloader/ModulesLoader.java
@@ -18,12 +18,12 @@
 public interface ModulesLoader {
 
 	/**
-	 * Load modules from the given directory, and return the set of resources containing all modules written.
+	 * Load modules from the given directory
 	 *
 	 * @param directory
 	 * @param modulesFinder
 	 * @param client the DatabaseClient to use for loading REST extensions
-	 * @return
+	 * @return the set of resources containing all modules written
 	 */
 	Set<Resource> loadModules(String directory, ModulesFinder modulesFinder, DatabaseClient client);
 
@@ -34,7 +34,7 @@ public interface ModulesLoader {
 	 * @param client
 	 * @param modulesFinder
 	 * @param paths the DatabaseClient to use for loading REST extensions
-	 * @return
+	 * @return the set of resources containing all modules written
 	 */
 	Set<Resource> loadModules(DatabaseClient client, ModulesFinder modulesFinder, String... paths);
 }
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/impl/AbstractStaticChecker.java b/src/main/java/com/marklogic/client/ext/modulesloader/impl/AbstractStaticChecker.java
@@ -85,7 +85,7 @@ protected void performBulkStaticCheck(List<DocumentFile> assets) {
 	 * in construct that statement, it cannot be distinguished from an error in the actual module. To turn this behavior
 	 * off, set "staticCheckLibraryModules" to false.
 	 *
-	 * @return
+	 * @return XQuery script
 	 */
 	protected String buildXqueryForStaticallyCheckingModule() {
 		String xquery =
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/impl/BaseModulesFinder.java b/src/main/java/com/marklogic/client/ext/modulesloader/impl/BaseModulesFinder.java
@@ -97,7 +97,7 @@ protected void addAssetDirectories(Modules modules, String baseDir) {
 	 * test cases to know that this is safe for sure.
 	 *
 	 * @param resourceFile
-	 * @return
+	 * @return decoded resource path
 	 */
 	protected String decodeAssetDirectoryResource(String resourceFile) {
 	    if (resourceFile.contains("%20")) {
@@ -143,7 +143,7 @@ protected void addTransforms(Modules modules, String baseDir) {
 	 * @param moduleType used for a log message
 	 * @param basePath
 	 * @param paths
-	 * @return
+	 * @return list of resources
 	 */
 	protected List<Resource> findResources(String moduleType, String basePath, String... paths) {
 		List<Resource> list = new ArrayList<>();
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/impl/DefaultFileFilter.java b/src/main/java/com/marklogic/client/ext/modulesloader/impl/DefaultFileFilter.java
@@ -15,11 +15,9 @@ public boolean accept(File f) {
     }
 
 	/**
-	 * Ignores the directory, returns false if the name starts with ".".
-	 *
 	 * @param dir
 	 * @param name
-	 * @return
+	 * @return Ignores the directory, returns false if the name starts with ".", otherwise true
 	 */
 	@Override
 	public boolean accept(File dir, String name) {
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/impl/DefaultModulesLoader.java b/src/main/java/com/marklogic/client/ext/modulesloader/impl/DefaultModulesLoader.java
@@ -159,7 +159,7 @@ public Set<Resource> loadModules(DatabaseClient client, ModulesFinder modulesFin
 	 * @param baseDir
 	 * @param modulesFinder
 	 * @param client
-	 * @return
+	 * @return the set of resources capturing each module that was written
 	 */
 	public Set<Resource> loadModules(String baseDir, ModulesFinder modulesFinder, DatabaseClient client) {
 		return loadModules(client, modulesFinder, baseDir);
@@ -502,7 +502,7 @@ protected void loadNamespaces(Modules modules, Set<Resource> loadedModules) {
 	 * @param r
 	 * @param metadata
 	 * @param methodParams
-	 * @return
+	 * @return the resource is one was installed, else null
 	 */
 	public Resource installService(Resource r, final ExtensionMetadata metadata, final MethodParameters... methodParams) {
 		if (!hasFileBeenModified(r) || ignoreResource(r)) {
@@ -531,7 +531,7 @@ public Resource installService(Resource r, final ExtensionMetadata metadata, fin
 	/**
 	 * @param r
 	 * @param metadata
-	 * @return
+	 * @return the resource is one was installed, else null
 	 */
 	public Resource installTransform(Resource r, final ExtensionMetadata metadata) {
 		if (!hasFileBeenModified(r) || ignoreResource(r)) {
@@ -562,7 +562,7 @@ public Resource installTransform(Resource r, final ExtensionMetadata metadata) {
 
 	/**
 	 * @param r
-	 * @return
+	 * @return the resource is one was installed, else null
 	 */
 	public Resource installQueryOptions(Resource r) {
 		if (!hasFileBeenModified(r) || ignoreResource(r)) {
@@ -628,7 +628,7 @@ protected void executeTask(Runnable r) {
 
 	/**
 	 * @param r
-	 * @return
+	 * @return the resource if one is installed, else null
 	 */
 	public Resource installNamespace(Resource r) {
 		if (!hasFileBeenModified(r) || ignoreResource(r)) {
@@ -658,7 +658,7 @@ public Resource installNamespace(Resource r) {
 
 	/**
 	 * @param r
-	 * @return
+	 * @return the extension name if one exists; if not, then the filename
 	 */
 	protected String getExtensionNameFromFile(Resource r) {
 		String name = r.getFilename();
@@ -674,7 +674,7 @@ protected String getExtensionNameFromFile(Resource r) {
 	 * resolved, then false is returned.
 	 *
 	 * @param r
-	 * @return
+	 * @return true if resource should be ignored
 	 */
 	protected boolean ignoreResource(Resource r) {
 		if (includeFilenamePattern != null) {
@@ -776,11 +776,9 @@ private void updateTimestamp(Resource resource) {
 	}
 
 	/**
-	 * Returns a string that is useful for logging information about the DatabaseClient connection before a call is
-	 * made to load a REST extension.
-	 *
 	 * @param client
-	 * @return
+	 * @return a string that is useful for logging information about the DatabaseClient connection before a call is
+	 * made to load a REST extension.
 	 */
 	protected String getDatabaseClientInfo(DatabaseClient client) {
 		String info = format("port: %d", client.getPort());
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/impl/PropertiesModuleManager.java b/src/main/java/com/marklogic/client/ext/modulesloader/impl/PropertiesModuleManager.java
@@ -83,7 +83,7 @@ public void deletePropertiesFile() {
 	/**
 	 *
 	 * @param file
-	 * @return
+	 * @return true if file has been modified
 	 */
 	@Override
 	public boolean hasFileBeenModifiedSinceLastLoaded(File file) {
@@ -127,7 +127,7 @@ public void saveLastLoadedTimestamp(File file, Date date) {
      * differing in some cases, but I'm not sure why anyone would do that.
      *
      * @param file
-     * @return
+     * @return a string that can be used as a key for a Properties object
      */
     protected String buildKey(File file) {
         String path = file.getAbsolutePath().toLowerCase();
diff --git a/src/main/java/com/marklogic/client/ext/modulesloader/ssl/SimpleX509TrustManager.java b/src/main/java/com/marklogic/client/ext/modulesloader/ssl/SimpleX509TrustManager.java
@@ -16,7 +16,7 @@ public class SimpleX509TrustManager implements X509TrustManager {
 	/**
 	 * Factory method for creating a simple SSLContext that uses this class as its TrustManager.
 	 *
-	 * @return
+	 * @return a default trust-everything SSLContext
 	 */
 	public static SSLContext newSSLContext() {
 		return newSSLContext(SslUtil.DEFAULT_SSL_PROTOCOL);
diff --git a/src/main/java/com/marklogic/client/ext/qconsole/impl/DefaultWorkspaceManager.java b/src/main/java/com/marklogic/client/ext/qconsole/impl/DefaultWorkspaceManager.java
@@ -108,9 +108,7 @@ protected String determineImportScriptToUse() {
 	}
 
 	/**
-	 * Defaults to ~/.qconsole/workspaces.
-	 *
-	 * @return
+	 * @return defaults to ~/.qconsole/workspaces
 	 */
 	protected File getDefaultWorkspacesDir() {
 		File homeDir = new File(System.getProperty("user.home"));
diff --git a/src/main/java/com/marklogic/client/ext/schemasloader/SchemasLoader.java b/src/main/java/com/marklogic/client/ext/schemasloader/SchemasLoader.java
@@ -11,7 +11,7 @@ public interface SchemasLoader {
 	 * path, along with how to load them.
 	 *
 	 * @param paths
-	 * @return
+	 * @return a DocumentFile for each file that was loaded from the given paths
 	 */
 	List<DocumentFile> loadSchemas(String... paths);
 }
diff --git a/src/main/java/com/marklogic/client/ext/schemasloader/impl/DefaultSchemasLoader.java b/src/main/java/com/marklogic/client/ext/schemasloader/impl/DefaultSchemasLoader.java
@@ -74,7 +74,7 @@ protected void initializeDefaultSchemasLoader() {
 	 * return the result.
 	 *
 	 * @param paths
-	 * @return
+	 * @return a DocumentFile for each file that was loaded as a schema
 	 */
 	@Override
 	public List<DocumentFile> loadSchemas(String... paths) {
diff --git a/src/main/java/com/marklogic/client/ext/ssl/SslUtil.java b/src/main/java/com/marklogic/client/ext/ssl/SslUtil.java
@@ -17,7 +17,7 @@ public abstract class SslUtil {
 	 * Configure an SSLContext and X509TrustManager with TLSv1.2 as the default protocol and the default algorithm of
 	 * TrustManagerFactory.
 	 *
-	 * @return
+	 * @return an SslConfig object based on default settings
 	 */
 	public static SslConfig configureUsingTrustManagerFactory() {
 		return configureUsingTrustManagerFactory(DEFAULT_SSL_PROTOCOL, null);
@@ -29,7 +29,7 @@ public static SslConfig configureUsingTrustManagerFactory() {
 	 * @param protocol  the protocol to use when getting an instance of an SSLContext
 	 * @param algorithm an optional algorithm to use for getting an instance of TrustManagerFactory; if not specified,
 	 *                  the default algorithm of TrustManagerFactory is used
-	 * @return
+	 * @return an SslConfig based on the given inputs
 	 */
 	public static SslConfig configureUsingTrustManagerFactory(String protocol, String algorithm) {
 		SSLContext sslContext;
diff --git a/src/main/java/com/marklogic/client/ext/tokenreplacer/FilePropertiesSource.java b/src/main/java/com/marklogic/client/ext/tokenreplacer/FilePropertiesSource.java
@@ -28,10 +28,8 @@ public Properties getProperties() {
 	}
 
 	/**
-	 * Return a Properties instance based on properties from the given File.
-	 *
 	 * @param file
-	 * @return
+	 * @return a Properties instance based on properties from the given File.
 	 */
 	protected Properties loadPropertiesFromFile(File file) {
 		Properties properties = new Properties();
diff --git a/src/main/java/com/marklogic/client/ext/xcc/DefaultDocumentWriteOperationAdapter.java b/src/main/java/com/marklogic/client/ext/xcc/DefaultDocumentWriteOperationAdapter.java
@@ -42,7 +42,7 @@ public Content adapt(DocumentWriteOperation operation) {
 	 * TODO Only adapts collections, quality, format, and permissions so far.
 	 *
 	 * @param handle
-	 * @return
+	 * @return a ContentCreateOptions based on the given metadata object
 	 */
 	protected ContentCreateOptions adaptMetadata(DocumentMetadataWriteHandle handle) {
 		ContentCreateOptions options = new ContentCreateOptions();

Original file line number	Diff line number	Diff line change
`@@ -60,6 +60,8 @@ task javadocJar(type: Jar, dependsOn: javadoc) {`
`60`	`60`	`from javadoc`
`61`	`61`	`}`
`62`	`62`	`javadoc.failOnError = false`
	`63`	`+// Ignores warnings on params that don't have descriptions, which is a little too noisy`
	`64`	`+javadoc.options.addStringOption('Xdoclint:none', '-quiet')`
`63`	`65`
`64`	`66`	`artifacts {`
`65`	`67`	`archives javadocJar, sourcesJar`
Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,7 @@ protected void performBulkStaticCheck(List<DocumentFile> assets) {`
`85`	`85`	`* in construct that statement, it cannot be distinguished from an error in the actual module. To turn this behavior`
`86`	`86`	`* off, set "staticCheckLibraryModules" to false.`
`87`	`87`	`*`
`88`		`- * @return`
	`88`	`+ * @return XQuery script`
`89`	`89`	`*/`
`90`	`90`	`protected String buildXqueryForStaticallyCheckingModule() {`
`91`	`91`	`String xquery =`