javadoc fixes for gestalt-module

gestalt-module/src/main/java/org/terasology/gestalt/i18n/I18nMap.java

@@ -67,6 +67,8 @@ public I18nMap(String value) {
     }
 
     /**
+     * The most appropraite value to use based on the system default locale.
+     *
      * @return The most appropriate string value to use based on the system default Locale
      */
     public String value() {
@@ -84,6 +86,8 @@ public String value() {
     }
 
     /**
+     * Get the string value for the locale passed.
+     *
      * @param locale The locale to get the string value for
      * @return The most appropriate string value for the given locale.
      */
@@ -104,6 +108,8 @@ public String valueFor(Locale locale) {
     }
 
     /**
+     * Convert to string.
+     *
      * @return The most appropriate string value based on the system default locale.
      */
     @Override

gestalt-module/src/main/java/org/terasology/gestalt/module/Module.java

@@ -71,57 +71,73 @@ public Module(ModuleMetadata metadata, ModuleFileSource fileSources, Collection<
     }
 
     /**
+     * Get resources for module.
+     *
      * @return A ModuleFileSource providing this module's resources
      */
     public ModuleFileSource getResources() {
         return moduleFileSources;
     }
 
     /**
+     * Get additional classpaths.
+     *
      * @return A list of additional classpaths to load
      */
     public List<File> getClasspaths() {
         return moduleClasspaths;
     }
 
     /**
+     * Get the identifier for the module.
+     *
      * @return The identifier for the module
      */
     public Name getId() {
         return metadata.getId();
     }
 
     /**
+     * Get the version of the module.
+     *
      * @return The version of the module
      */
     public Version getVersion() {
         return metadata.getVersion();
     }
 
     /**
+     * Get the permissions required by the module.
+     *
      * @return The list of permission sets required by this module
      */
     public ImmutableSet<String> getRequiredPermissions() {
         return ImmutableSet.copyOf(metadata.getRequiredPermissions());
     }
 
     /**
+     * Get the metadata of the module.
+     *
      * @return Metadata describing the module
      */
     public ModuleMetadata getMetadata() {
         return metadata;
     }
 
     /**
+     * Get information on the contents on this module.
+     *
      * @return Information on the contents on this module
      */
     public ClassIndex getClassIndex() {
         return classIndex;
     }
 
     /**
-     * @return A predicate that specifies whether a given class from the main classloader is a
-     * member of this module
+     * Gets a predicate which that specifies whether a given class from the main classloader is a
+     * member of this module.
+     *
+     * @return A predicate
      */
     public Predicate<Class<?>> getClassPredicate() {
         return classPredicate;

gestalt-module/src/main/java/org/terasology/gestalt/module/ModuleEnvironment.java

@@ -84,6 +84,9 @@ public class ModuleEnvironment implements AutoCloseable, Iterable<Module> {
     private final ModuleFileSource resources;
 
     /**
+     * Constructor.
+     *
+     * @param beanContext               The bean context.
      * @param modules                   The modules this environment should encompass.
      * @param permissionProviderFactory A factory for producing a PermissionProvider for each loaded module
      * @throws java.lang.IllegalArgumentException if the Iterable contains multiple modules with the same id.
@@ -93,6 +96,9 @@ public ModuleEnvironment(BeanContext beanContext, Iterable<Module> modules, Perm
     }
 
     /**
+     * Constructor.
+     *
+     * @param beanContext               The bean context.
      * @param modules                   The modules this environment should encompass.
      * @param permissionProviderFactory A factory for producing a PermissionProvider for each loaded module
      * @param classLoaderSupplier       A supplier for producing a ModuleClassLoader for a module
@@ -103,14 +109,18 @@ public ModuleEnvironment(BeanContext beanContext, Iterable<Module> modules, Perm
     }
 
     /**
+     * Constructor.
+     *
+     * @param beanContext               The bean context.
      * @param modules                   The modules this environment should encompass.
-     * @param permissionProviderFactory A factory for producing a PermissionProvider for each loaded module
-     * @param classLoaderSupplier       A supplier for producing a ModuleClassLoader for a module
+     * @param permissionProviderFactory A factory for producing a PermissionProvider for each loaded module.
+     * @param classLoaderSupplier       A supplier for producing a ModuleClassLoader for a module.
      * @param apiClassLoader            The base classloader the module environment should build upon.
      * @throws java.lang.IllegalArgumentException if the Iterable contains multiple modules with the same id.
      */
-    public ModuleEnvironment(BeanContext beanContext, Iterable<Module> modules, final PermissionProviderFactory permissionProviderFactory, ClassLoaderSupplier classLoaderSupplier, ClassLoader apiClassLoader) {
-
+    public ModuleEnvironment(BeanContext beanContext, Iterable<Module> modules,
+                             final PermissionProviderFactory permissionProviderFactory,
+                             ClassLoaderSupplier classLoaderSupplier, ClassLoader apiClassLoader) {
         this.modules = buildModuleMap(modules);
         this.apiClassLoader = apiClassLoader;
         this.modulesOrderByDependencies = calculateModulesOrderedByDependencies();
@@ -243,6 +253,8 @@ public void close() {
     }
 
     /**
+     * Gets a module for a specified id.
+     *
      * @param id The id of the module to return
      * @return The desired module, or null if it is not part of the environment
      */
@@ -261,6 +273,9 @@ public final List<Module> getModulesOrderedByDependencies() {
     }
 
     /**
+     * List of module ids sorted so that dependencies appear before modules that depend on them. Additionally,
+     * modules are alphabetically ordered where there are no dependencies.
+     *
      * @return A list of modules in the environment, sorted so any dependencies appear before a module
      */
     public final List<Name> getModuleIdsOrderedByDependencies() {
@@ -287,6 +302,8 @@ public Name getModuleProviding(Class<?> type) {
     }
 
     /**
+     * Get the ids of the dependencies of the desired module.
+     *
      * @param moduleId The id of the module to get the dependencies
      * @return The ids of the dependencies of the desired module
      */
@@ -295,13 +312,17 @@ public Set<Name> getDependencyNamesOf(Name moduleId) {
     }
 
     /**
-     * @return The available resources across all modules
+     * Get available resources across all modules.
+     *
+     * @return The available resources
      */
     public ModuleFileSource getResources() {
         return resources;
     }
 
     /**
+     * Get an iterable over all subtypes of the type that appears in the module environment.
+     *
      * @param type The type to find subtypes of
      * @param <U>  The type to find subtypes of
      * @return A Iterable over all subtypes of type that appear in the module environment
@@ -316,10 +337,12 @@ public <U> Iterable<Class<? extends U>> getSubtypesOf(Class<U> type) {
     }
 
     /**
+     * Get an iterable over all subtypes of the type that appears in the module environment, filtered.
+     *
      * @param type   The type to find subtypes of
      * @param <U>    The type to find subtypes of
      * @param filter A filter to apply to the returned subtypes
-     * @return A Iterable over all subtypes of type that appear in the module environment
+     * @return A Iterable over all subtypes of type
      */
     public <U> Iterable<Class<? extends U>> getSubtypesOf(Class<U> type, Predicate<Class<?>> filter) {
         return classIndexByModule.entrySet().stream()
@@ -332,9 +355,11 @@ public <U> Iterable<Class<? extends U>> getSubtypesOf(Class<U> type, Predicate<C
     }
 
     /**
+     * Get all types in the environment that are either marked by the given annotation, or are subtypes of a type marked
+     * with the annotation if the annotation is marked as @Inherited.
+     *
      * @param annotation The annotation of interest
-     * @return All types in the environment that are either marked by the given annotation, or are subtypes of a type marked with the annotation if the annotation is marked
-     * as @Inherited
+     * @return  All types that are marked by the given annotation, or are subtypes
      */
     public Iterable<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> annotation) {
         return classIndexByModule.entrySet().stream()
@@ -346,10 +371,12 @@ public Iterable<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> anno
     }
 
     /**
+     * Get all types in the environment that are either marked by the given annotation, or are subtypes of a type marked
+     * with the annotation if the annotation is marked as @Inherited, filtered.
+     *
      * @param annotation The annotation of interest
      * @param filter     Further filter on the returned types
-     * @return All types in the environment that are either marked by the given annotation, or are subtypes of a type marked with the annotation if the annotation is marked
-     * as @Inherited
+     * @return All types in the environment marked by the given annotation or are subtypes
      */
     public Iterable<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> annotation, Predicate<Class<?>> filter) {
         return classIndexByModule.entrySet().stream()
@@ -367,6 +394,13 @@ public Iterator<Module> iterator() {
         return modules.values().iterator();
     }
 
+    /**
+     * Get beans implementing this interface.
+     *
+     * @param <T>               the type to extend
+     * @param interfaceClass    the interface class
+     * @return beans for this interface.
+     */
     public <T> List<? extends T> getBeans(Class<T> interfaceClass) {
         return finalBeanContext.getBeans(interfaceClass);
     }
@@ -384,8 +418,18 @@ private Class<?> loadClass(ClassLoader classLoader, String clazzName) {
     }
 
 
+    /**
+     * Functional interface.
+     */
     @FunctionalInterface
     public interface ClassLoaderSupplier {
+        /**
+         * Creats a module class loader
+         * @param module                the module
+         * @param parent                the parent classloader
+         * @param permissionProvider    the permission provider
+         * @return  the module classloader
+         */
         ModuleClassLoader create(Module module, ClassLoader parent, PermissionProvider permissionProvider);
     }
 

gestalt-module/src/main/java/org/terasology/gestalt/module/ModuleFactory.java

@@ -69,19 +69,26 @@ public class ModuleFactory {
     private String defaultLibsSubpath;
     private boolean scanningForClasses = true;
 
+
+    /**
+     * Default constructor.
+     */
     @Inject // TODO use another constructor.
     public ModuleFactory() {
         this(Thread.currentThread().getContextClassLoader());
     }
 
     /**
+     * Constructor.
      * @param classLoader The classloader to use for classpath and package modules
      */
     public ModuleFactory(ClassLoader classLoader) {
         this(classLoader, STANDARD_CODE_SUBPATH, STANDARD_LIBS_SUBPATH, ImmutableMap.of("module.json", new ModuleMetadataJsonAdapter()));
     }
 
     /**
+     * Constructor with code libs subpath.
+     *
      * @param defaultCodeSubpath The default subpath in a path module that contains code (compiled class files)
      * @param defaultLibsSubpath The default subpath in a path module that contains libraries (jars)
      */
@@ -90,6 +97,7 @@ public ModuleFactory(String defaultCodeSubpath, String defaultLibsSubpath) {
     }
 
     /**
+     * Constructor with classLoader, code, moodule subpath, metadata loaders.
      * @param classLoader        The classloader that modules should be loaded atop of
      * @param defaultCodeSubpath The default subpath in a path module that contains code (compiled class files)
      * @param defaultLibsSubpath The default subpath in a path module that contains libraries (jars)
@@ -103,6 +111,8 @@ public ModuleFactory(ClassLoader classLoader, String defaultCodeSubpath, String
     }
 
     /**
+     * Get the modules code subpath.
+     *
      * @return The subpath of a path module that contains compiled code
      */
     public String getDefaultCodeSubpath() {
@@ -119,20 +129,26 @@ public void setDefaultCodeSubpath(String defaultCodeSubpath) {
     }
 
     /**
-     * @return Whether the module factory will scan modules for class files if a manifest isn't available
+     * Whether the module factory will scan modules for class files if a manifest isn't available.
+     *
+     * @return The module factory will scan modules for class files if true and a manifest isn't available
      */
     public boolean isScanningForClasses() {
         return scanningForClasses;
     }
 
     /**
-     * @param scanForClasses Whether the module factory should scan modules for class files if a manifest isn't present
+     * Set if the module factory should scan modules for class files if a manifest isn't present.
+     *
+     * @param scanForClasses when true, the module factory scans modules for class files if a manifest isn't present
      */
     public void setScanningForClasses(boolean scanForClasses) {
         this.scanningForClasses = scanForClasses;
     }
 
     /**
+     * Gets the modules subpath that contains libraries.
+     *
      * @return The subpath of a path module that contains libraries
      */
     public String getDefaultLibsSubpath() {
@@ -149,7 +165,8 @@ public void setDefaultLibsSubpath(String defaultLibsSubpath) {
     }
 
     /**
-     * @return The map of paths to module metadata loaders used for loading metadata describing modules
+     * Get a map of paths to module metadata loaders used for loading metadata describing modules.
+     * @return The map of paths to module metadata loaders used for loading metadata
      */
     public Map<String, ModuleMetadataLoader> getModuleMetadataLoaderMap() {
         return moduleMetadataLoaderMap;