* Fixed a bunch of checkstyle violations (mostly

javadoc)

* Added basic javadoc target to build.


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272154 13f79535-47bb-0310-9956-ffa450edef68

proposal/myrmidon/build.xml

@@ -651,6 +651,8 @@ Legal:
 
     <target name="checkstyle" description="Checkstyle">
 
+        <property name="checkstyle.dir" value="${java.dir}"/>
+
         <!-- this invocation of checkstyle requires that checkstyle be downloaded and setup -->
         <!-- thats why you are required to define do.checkstyle property to generate the report -->
         <taskdef name="checkstyle"
@@ -678,7 +680,7 @@ Legal:
             cacheFile="checkstyle.cache"
             failOnViolation="false"
             ignoreCastWhitespace="true">
-            <fileset dir="${java.dir}">
+            <fileset dir="${checkstyle.dir}">
                 <include name="**/*.java"/>
             </fileset>
             <formatter type="plain"/>
@@ -740,6 +742,18 @@ Legal:
             />
     </target>
 
+    <target name="javadoc" description="Generates the API docs.">
+        <property name="build.apidocs" value="${build.dir}/apidocs"/>
+        <mkdir dir="${build.apidocs}"/>
+
+        <javadoc destdir="${build.apidocs}" packagenames="org.apache.*">
+            <sourcepath>
+                <pathelement location="${java.dir}"/>
+            </sourcepath>
+            <classpath refid="project.class.path"/>
+        </javadoc>
+    </target>
+
     <!-- Creates the distribution -->
     <target name="dist-lite"
         depends="jars"

proposal/myrmidon/src/java/org/apache/myrmidon/components/builder/ConvertingProjectBuilder.java

@@ -27,6 +27,13 @@ public class ConvertingProjectBuilder
 {
     private static final String VERSION_ATTRIBUTE = "version";
 
+    /**
+     * Builds a Configuration from an Ant1 project file, converting it
+     * into a valid Myrmidon Project.
+     * @param systemID the xml Systemid of the project file.
+     * @return the configured project
+     * @throws ProjectException if an error occurs parsing the project file
+     */
     protected Configuration parseProject( String systemID )
         throws ProjectException
     {

proposal/myrmidon/src/java/org/apache/myrmidon/components/builder/DefaultProject.java

@@ -50,7 +50,7 @@ public class DefaultProject
     private String m_name;
 
     /**
-     * Returns the project name.
+     * @return the project name.
      */
     public String getProjectName()
     {
@@ -59,6 +59,7 @@ public class DefaultProject
 
     /**
      * Sets the project name.
+     * @param name the project name
      */
     public void setProjectName( String name )
     {
@@ -169,7 +170,8 @@ public class DefaultProject
     }
 
     /**
-     * Retrieve base directory of project.
+     * Sets the project base directory.
+     * @param baseDirectory the base directory for the project
      */
     public final void setBaseDirectory( final File baseDirectory )
     {
@@ -178,6 +180,7 @@ public class DefaultProject
 
     /**
      * Adds a type library import to the project.
+     * @param typeLib the type library
      */
     public final void addTypeLib( final TypeLib typeLib )
     {

proposal/myrmidon/src/java/org/apache/myrmidon/components/builder/DefaultProjectBuilder.java

@@ -96,13 +96,17 @@ public class DefaultProjectBuilder
         }
         catch( Exception e )
         {
-            final String message = REZ.getString( "ant.project-build.error", file.getAbsolutePath() );
+            final String message = REZ.getString( "ant.project-build.error",
+                                                  file.getAbsolutePath() );
             throw new ProjectException( message, e );
         }
     }
 
     /**
-     * Parses the project.
+     * Builds a project configuration from a build file.
+     * @param systemID the XML system id of the build file
+     * @return the project configuration
+     * @throws ProjectException on parse error
      */
     protected Configuration parseProject( final String systemID )
         throws ProjectException
@@ -172,7 +176,8 @@ public class DefaultProjectBuilder
 
         if( getLogger().isDebugEnabled() )
         {
-            final String message = REZ.getString( "ant.project-banner.notice", file, baseDirectory );
+            final String message = REZ.getString( "ant.project-banner.notice",
+                                                  file, baseDirectory );
             getLogger().debug( message );
         }
 
@@ -189,7 +194,8 @@ public class DefaultProjectBuilder
      * Get the project name from the configuration, or create a default name if none
      * was supplied.
      */
-    private String getProjectName( final Configuration configuration, final File file )
+    private String getProjectName( final Configuration configuration,
+                                   final File file )
         throws ProjectException
     {
         String projectName = configuration.getAttribute( "name", null );
@@ -332,7 +338,8 @@ public class DefaultProjectBuilder
             else
             {
                 final String message =
-                    REZ.getString( "ant.unknown-toplevel-element.error", name, element.getLocation() );
+                    REZ.getString( "ant.unknown-toplevel-element.error", name,
+                                   element.getLocation() );
                 throw new ProjectException( message );
             }
         }
@@ -355,7 +362,8 @@ public class DefaultProjectBuilder
         if( null == name )
         {
             final String message =
-                REZ.getString( "ant.projectref-no-name.error", element.getLocation() );
+                REZ.getString( "ant.projectref-no-name.error",
+                               element.getLocation() );
             throw new ProjectException( message );
         }
 
@@ -366,14 +374,16 @@ public class DefaultProjectBuilder
         catch( Exception e )
         {
             final String message =
-                REZ.getString( "ant.projectref-bad-name.error", element.getLocation() );
+                REZ.getString( "ant.projectref-bad-name.error",
+                               element.getLocation() );
             throw new ProjectException( message, e );
         }
 
         if( null == location )
         {
             final String message =
-                REZ.getString( "ant.projectref-no-location.error", element.getLocation() );
+                REZ.getString( "ant.projectref-no-location.error",
+                               element.getLocation() );
             throw new ProjectException( message );
         }
 
@@ -487,7 +497,8 @@ public class DefaultProjectBuilder
         }
     }
 
-    private Dependency[] buildDependsList( final String depends, final Configuration target )
+    private Dependency[] buildDependsList( final String depends,
+                                           final Configuration target )
         throws ProjectException
     {
         //apply depends attribute
@@ -505,7 +516,8 @@ public class DefaultProjectBuilder
 
             if( getLogger().isDebugEnabled() )
             {
-                final String message = REZ.getString( "ant.target-dependency.notice", dependency );
+                final String message = REZ.getString( "ant.target-dependency.notice",
+                                                      dependency );
                 getLogger().debug( message );
             }
 
@@ -524,7 +536,8 @@ public class DefaultProjectBuilder
                 targetName = dependency;
             }
 
-            if( targetName.length() == 0 || ( projectName != null && projectName.length() == 0 ) )
+            if( targetName.length() == 0 ||
+                ( projectName != null && projectName.length() == 0 ) )
             {
                 final String message = REZ.getString( "ant.target-bad-dependency.error",
                                                       target.getName(),

proposal/myrmidon/src/java/org/apache/myrmidon/components/builder/TransformingProjectBuilder.java

@@ -38,6 +38,13 @@ public class TransformingProjectBuilder
     private static final String STYLESHEET = "ant1convert.xsl";
     private Transformer m_transformer;
 
+    /**
+     * Builds a project Configuration from a project file, applying the
+     * ant1 conversion stylesheet.
+     * @param systemID the XML system id for the project file
+     * @return the project configuration
+     * @throws ProjectException if a parse error occurs
+     */
     protected Configuration parseProject( String systemID )
         throws ProjectException
     {

proposal/myrmidon/src/java/org/apache/myrmidon/components/configurer/ClassicConfigurer.java

@@ -154,7 +154,8 @@ public class ClassicConfigurer
 
                 if( DEBUG )
                 {
-                    final String message = REZ.getString( "configure-attribute.notice", name, value );
+                    final String message = REZ.getString( "configure-attribute.notice",
+                                                          name, value );
                     getLogger().debug( message );
                 }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/configurer/DefaultConfigurer.java

@@ -104,7 +104,8 @@ public class DefaultConfigurer
         catch( final Exception e )
         {
             // Wrap all other errors with general purpose error message
-            final String message = REZ.getString( "bad-configure-element.error", configuration.getName() );
+            final String message = REZ.getString( "bad-configure-element.error",
+                                                  configuration.getName() );
             throw new ConfigurationException( message, e );
         }
     }
@@ -426,7 +427,8 @@ public class DefaultConfigurer
         else
         {
             // Set the value
-            PropertyConfigurer propConfigurer = getConfigurerFromName( state.getConfigurer(), name, false, false );
+            PropertyConfigurer propConfigurer =
+                getConfigurerFromName( state.getConfigurer(), name, false, false );
             setValue( propConfigurer, state, value, context );
         }
     }
@@ -558,7 +560,8 @@ public class DefaultConfigurer
                 else
                 {
                     // Check the role name
-                    final RoleInfo roleInfo = m_roleManager.getRoleByType( propertyConfigurer.getType() );
+                    final RoleInfo roleInfo =
+                        m_roleManager.getRoleByType( propertyConfigurer.getType() );
                     if( roleInfo != null && name.equalsIgnoreCase( roleInfo.getShorthand() ) )
                     {
                         return propertyConfigurer;

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/Deployment.java

@@ -85,7 +85,8 @@ class Deployment
 
         // Build the role descriptors
         final ArrayList roleUrls = locateResources( ROLE_DESCRIPTOR_NAME, jarUrl );
-        final ArrayList roleDescriptors = buildDescriptors( roleUrls, m_roleBuilder, parser, handler );
+        final ArrayList roleDescriptors =
+            buildDescriptors( roleUrls, m_roleBuilder, parser, handler );
 
         // Deploy the roles
         // TODO - need to defer this
@@ -98,13 +99,17 @@ class Deployment
 
         // Build the type descriptors
         final ArrayList typeUrls = locateResources( TYPE_DESCRIPTOR_NAME, jarUrl );
-        final ArrayList typeDescriptors = buildDescriptors( typeUrls, m_typeBuilder, parser, handler );
-        m_descriptors = (TypeDescriptor[])typeDescriptors.toArray( new TypeDescriptor[ typeDescriptors.size() ] );
+        final ArrayList typeDescriptors =
+            buildDescriptors( typeUrls, m_typeBuilder, parser, handler );
+        m_descriptors = (TypeDescriptor[])typeDescriptors.toArray
+            ( new TypeDescriptor[ typeDescriptors.size() ] );
 
         // Build the service descriptors
         final ArrayList serviceUrls = locateResources( SERVICE_DESCRIPTOR_NAME, jarUrl );
-        final ArrayList serviceDescriptors = buildDescriptors( serviceUrls, m_serviceBuilder, parser, handler );
-        m_services = (ServiceDescriptor[])serviceDescriptors.toArray( new ServiceDescriptor[ serviceDescriptors.size() ] );
+        final ArrayList serviceDescriptors =
+            buildDescriptors( serviceUrls, m_serviceBuilder, parser, handler );
+        m_services = (ServiceDescriptor[])serviceDescriptors.toArray
+            ( new ServiceDescriptor[ serviceDescriptors.size() ] );
     }
 
     /**
@@ -198,7 +203,8 @@ class Deployment
         }
         catch( Exception e )
         {
-            final String message = REZ.getString( "deploy-type.error", typeDef.getRole(), typeDef.getName() );
+            final String message = REZ.getString( "deploy-type.error",
+                                                  typeDef.getRole(), typeDef.getName() );
             throw new DeploymentException( message, e );
         }
     }
@@ -220,7 +226,8 @@ class Deployment
 
             // Parse the file
             parser.parse( url );
-            final TypelibDescriptor descriptor = builder.createDescriptor( handler.getConfiguration(), url );
+            final TypelibDescriptor descriptor =
+                builder.createDescriptor( handler.getConfiguration(), url );
             descriptors.add( descriptor );
         }
 
@@ -274,7 +281,8 @@ class Deployment
         {
             if( getLogger().isDebugEnabled() )
             {
-                final String message = REZ.getString( "url-deploy-roles.notice", descriptor.getUrl() );
+                final String message =
+                    REZ.getString( "url-deploy-roles.notice", descriptor.getUrl() );
                 getLogger().debug( message );
             }
 
@@ -302,7 +310,8 @@ class Deployment
         {
             if( getLogger().isDebugEnabled() )
             {
-                final String message = REZ.getString( "url-deploy-types.notice", descriptor.getUrl() );
+                final String message =
+                    REZ.getString( "url-deploy-types.notice", descriptor.getUrl() );
                 getLogger().debug( message );
             }
 
@@ -332,7 +341,8 @@ class Deployment
         {
             if( getLogger().isDebugEnabled() )
             {
-                final String message = REZ.getString( "url-deploy-services.notice", descriptor.getUrl() );
+                final String message =
+                    REZ.getString( "url-deploy-services.notice", descriptor.getUrl() );
                 getLogger().debug( message );
             }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/RoleDescriptor.java

@@ -31,7 +31,8 @@ class RoleDescriptor
      */
     public RoleDefinition[] getDefinitions()
     {
-        return (RoleDefinition[])m_definitions.toArray( new RoleDefinition[ m_definitions.size() ] );
+        return (RoleDefinition[])m_definitions.toArray
+            ( new RoleDefinition[ m_definitions.size() ] );
     }
 
     /**

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/RoleDescriptorBuilder.java

@@ -41,7 +41,8 @@ class RoleDescriptorBuilder
             final Version version = Version.getVersion( versionString );
             if( !ROLE_DESCRIPTOR_VERSION.complies( version ) )
             {
-                final String message = REZ.getString( "role-descriptor-version.error", version, ROLE_DESCRIPTOR_VERSION );
+                final String message = REZ.getString( "role-descriptor-version.error",
+                                                      version, ROLE_DESCRIPTOR_VERSION );
                 throw new DeploymentException( message );
             }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/ServiceDescriptor.java

@@ -28,7 +28,8 @@ class ServiceDescriptor
 
     public ServiceDefinition[] getDefinitions()
     {
-        return (ServiceDefinition[])m_services.toArray( new ServiceDefinition[ m_services.size() ] );
+        return (ServiceDefinition[])m_services.toArray
+            ( new ServiceDefinition[ m_services.size() ] );
     }
 
     public void addDefinition( final ServiceDefinition definition )

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/ServiceDescriptorBuilder.java

@@ -41,7 +41,8 @@ class ServiceDescriptorBuilder
             final Version version = Version.getVersion( versionString );
             if( !SERVICE_DESCRIPTOR_VERSION.complies( version ) )
             {
-                final String message = REZ.getString( "service-descriptor-version.error", version, SERVICE_DESCRIPTOR_VERSION );
+                final String message = REZ.getString( "service-descriptor-version.error",
+                                                      version, SERVICE_DESCRIPTOR_VERSION );
                 throw new DeploymentException( message );
             }
 
@@ -55,7 +56,8 @@ class ServiceDescriptorBuilder
                 final Configuration element = elements[ i ];
                 final String roleShorthand = element.getName();
                 final String factoryClassName = element.getAttribute( "factory" );
-                final ServiceDefinition definition = new ServiceDefinition( roleShorthand, factoryClassName, config );
+                final ServiceDefinition definition =
+                    new ServiceDefinition( roleShorthand, factoryClassName, config );
                 descriptor.addDefinition( definition );
             }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/TypeDescriptor.java

@@ -29,7 +29,8 @@ class TypeDescriptor
 
     public TypeDefinition[] getDefinitions()
     {
-        return (TypeDefinition[])m_definitions.toArray( new TypeDefinition[ m_definitions.size() ] );
+        return (TypeDefinition[])m_definitions.toArray
+            ( new TypeDefinition[ m_definitions.size() ] );
     }
 
     public void addDefinition( final TypeDefinition def )

proposal/myrmidon/src/java/org/apache/myrmidon/components/deployer/TypeDescriptorBuilder.java

@@ -44,7 +44,8 @@ class TypeDescriptorBuilder
             final Version version = Version.getVersion( versionString );
             if( !TYPE_DESCRIPTOR_VERSION.complies( version ) )
             {
-                final String message = REZ.getString( "type-descriptor-version.error", version, TYPE_DESCRIPTOR_VERSION );
+                final String message = REZ.getString( "type-descriptor-version.error",
+                                                      version, TYPE_DESCRIPTOR_VERSION );
                 throw new DeploymentException( message );
             }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/embeddor/DefaultEmbeddor.java

@@ -175,7 +175,8 @@ public class DefaultEmbeddor
 
         // setup a service manager that creates the project services
         final ServiceManager projServiceManager
-            = (ServiceManager)createService( ServiceManager.class, PREFIX + "service.InstantiatingServiceManager" );
+            = (ServiceManager)createService( ServiceManager.class,
+                                             PREFIX + "service.InstantiatingServiceManager" );
         setupObject( projServiceManager, m_serviceManager, m_parameters );
 
         // setup a service manager to be used by workspaces
@@ -267,7 +268,8 @@ public class DefaultEmbeddor
         createComponent( RoleManager.class, PREFIX + "role.DefaultRoleManager" );
         createComponent( AspectManager.class, PREFIX + "aspect.DefaultAspectManager" );
         createComponent( Deployer.class, PREFIX + "deployer.DefaultDeployer" );
-        createComponent( ClassLoaderManager.class, PREFIX + "classloader.DefaultClassLoaderManager" );
+        createComponent( ClassLoaderManager.class,
+                         PREFIX + "classloader.DefaultClassLoaderManager" );
         createComponent( Executor.class, PREFIX + "executor.AspectAwareExecutor" );
         createComponent( PropertyResolver.class, PREFIX + "property.DefaultPropertyResolver" );
 
@@ -388,7 +390,8 @@ public class DefaultEmbeddor
 
             if( !roleType.isInstance( object ) )
             {
-                final String message = REZ.getString( "bad-type.error", className, roleType.getName() );
+                final String message = REZ.getString( "bad-type.error",
+                                                      className, roleType.getName() );
                 throw new Exception( message );
             }
 
@@ -396,7 +399,8 @@ public class DefaultEmbeddor
         }
         catch( final IllegalAccessException iae )
         {
-            final String message = REZ.getString( "bad-ctor.error", roleType.getName(), className );
+            final String message = REZ.getString( "bad-ctor.error",
+                                                  roleType.getName(), className );
             throw new Exception( message );
         }
         catch( final InstantiationException ie )

proposal/myrmidon/src/java/org/apache/myrmidon/components/executor/DefaultExecutor.java

@@ -75,7 +75,8 @@ public class DefaultExecutor
         catch( Exception e )
         {
             // Wrap in generic error message
-            final String message = REZ.getString( "execute.error", taskName, taskModel.getLocation() );
+            final String message = REZ.getString( "execute.error",
+                                                  taskName, taskModel.getLocation() );
             throw new TaskException( message, e );
         }
     }

proposal/myrmidon/src/java/org/apache/myrmidon/components/service/InstantiatingServiceManager.java

@@ -188,7 +188,8 @@ public class InstantiatingServiceManager
             final Class serviceType = roleInfo.getType();
             if( serviceType != null && !serviceType.isInstance( service ) )
             {
-                final String message = REZ.getString( "mismatched-service-type.error", serviceRole, service.getClass().getName() );
+                final String message = REZ.getString( "mismatched-service-type.error",
+                                                      serviceRole, service.getClass().getName() );
                 throw new ServiceException( message );
             }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/type/MultiSourceTypeFactory.java

@@ -84,7 +84,8 @@ public class MultiSourceTypeFactory
         final Object object = factory.create( name );
         if( m_type != null && !m_type.isInstance( object ) )
         {
-            final String message = REZ.getString( "mismatched-type.error", name, object.getClass().getName() );
+            final String message = REZ.getString( "mismatched-type.error",
+                                                  name, object.getClass().getName() );
             throw new TypeException( message );
         }
 

proposal/myrmidon/src/java/org/apache/myrmidon/components/workspace/DefaultWorkspace.java

@@ -203,7 +203,8 @@ public class DefaultWorkspace
             }
             catch( final DeploymentException de )
             {
-                final String message = REZ.getString( "no-deploy.error", typeLib.getLibrary(), file );
+                final String message = REZ.getString( "no-deploy.error",
+                                                      typeLib.getLibrary(), file );
                 throw new TaskException( message, de );
             }
         }
@@ -416,7 +417,8 @@ public class DefaultWorkspace
 
         if( getLogger().isDebugEnabled() )
         {
-            final String message = REZ.getString( "exec-target.notice", project.getProjectName(), name );
+            final String message = REZ.getString( "exec-target.notice",
+                                                  project.getProjectName(), name );
             getLogger().debug( message );
         }
 

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/aspect/AspectManager.java

@@ -21,16 +21,39 @@ import org.apache.myrmidon.aspects.AspectHandler;
 public interface AspectManager
     extends AspectHandler
 {
+    /** Role name for this interface. */
     String ROLE = AspectManager.class.getName();
 
+    /**
+     * @return The names of all AspectHandlers managed.
+     */
     String[] getNames();
 
+    /**
+     * Dispatches aspect settings to the named AspectHandler.
+     * @param name The name of the AspectHandler to recieve the settings.
+     * @param parameters The parameter settings.
+     * @param elements The nested Configuration settings.
+     * @throws TaskException if the named AspectHandler doesn't exist,
+     *                  or it cannot handle the settings.
+     */
     void dispatchAspectSettings( String name, Parameters parameters, Configuration[] elements )
         throws TaskException;
 
+    /**
+     * Adds a named aspect handler to the manager.
+     * @param name The name used to lookup the aspect handler.
+     * @param handler The aspect handler to add.
+     * @throws TaskException If an error occurs.
+     */
     void addAspectHandler( String name, AspectHandler handler )
         throws TaskException;
 
+    /**
+     * Removes a named aspect handler from the manager.
+     * @param name The name of the handler to remove.
+     * @throws TaskException If the named handler doesn't exist.
+     */
     void removeAspectHandler( String name )
         throws TaskException;
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/builder/ProjectBuilder.java

@@ -18,6 +18,7 @@ import org.apache.myrmidon.interfaces.model.Project;
  */
 public interface ProjectBuilder
 {
+    /** Role name for this interface. */
     String ROLE = ProjectBuilder.class.getName();
 
     /**

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/classloader/ClassLoaderManager.java

@@ -16,10 +16,14 @@ import java.io.File;
  */
 public interface ClassLoaderManager
 {
+    /** Role name for this interface. */
     String ROLE = ClassLoaderManager.class.getName();
 
     /**
      * Builds the ClassLoader for a Jar file, resolving dependencies.
+     * @param jar the jar file containing the classes to load
+     * @return the created classloader
+     * @throws ClassLoaderException on error
      */
     ClassLoader createClassLoader( File jar ) throws ClassLoaderException;
 
@@ -28,12 +32,15 @@ public interface ClassLoaderManager
      *
      * @param jars The Jar/zip files to create the classloader for.  Use null
      *             or an empty array to use the common classloader.
+     * @return the created ClassLoader
+     * @throws ClassLoaderException on error
      */
     ClassLoader createClassLoader( File[] jars ) throws ClassLoaderException;
 
     /**
-     * Returns the common ClassLoader.  This is the parent of all classloaders
+     * Provides the common ClassLoader, which is the parent of all classloaders
      * built by this ClassLoaderManager.
+     * @return the common ClassLoader
      */
     ClassLoader getCommonClassLoader();
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/configurer/Configurer.java

@@ -20,6 +20,7 @@ import org.apache.myrmidon.api.TaskContext;
  */
 public interface Configurer
 {
+    /** Role name for this interface. */
     String ROLE = Configurer.class.getName();
 
     /**

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/converter/ConverterRegistry.java

@@ -15,6 +15,7 @@ package org.apache.myrmidon.interfaces.converter;
  */
 public interface ConverterRegistry
 {
+    /** Role name for this interface. */
     String ROLE = ConverterRegistry.class.getName();
 
     /**

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/deployer/ConverterDefinition.java

@@ -8,7 +8,7 @@
 package org.apache.myrmidon.interfaces.deployer;
 
 /**
- * A converter definition.
+ * A specialised TypeDefinition which defines a converter.
  *
  * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
  * @version $Revision$ $Date$
@@ -19,6 +19,12 @@ public class ConverterDefinition
     private final String m_sourceType;
     private final String m_destinationType;
 
+    /**
+     * Creates a converter definition.
+     * @param className the name of the implementing class
+     * @param sourceType the name of the types converted from
+     * @param destinationType the name of the type converted to
+     */
     public ConverterDefinition( final String className,
                                 final String sourceType,
                                 final String destinationType )
@@ -29,7 +35,8 @@ public class ConverterDefinition
     }
 
     /**
-     * Returns the converter's source type.
+     * Provides the name of the type which this converter can convert from.
+     * @return the converter's source type.
      */
     public String getSourceType()
     {
@@ -37,7 +44,8 @@ public class ConverterDefinition
     }
 
     /**
-     * Returns the converter's destination type.
+     * Provides the name of the type which this converter can convert to.
+     * @return the converter's destination type.
      */
     public String getDestinationType()
     {

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/deployer/Deployer.java

@@ -19,6 +19,7 @@ import org.apache.avalon.framework.service.ServiceManager;
  */
 public interface Deployer
 {
+    /** Role name for this interface. */
     String ROLE = Deployer.class.getName();
 
     /**
@@ -26,6 +27,7 @@ public interface Deployer
      * creating the deployer if necessary.
      *
      * @param loader The ClassLoader to get the deployer for.
+     * @return the deployer for this loader.
      * @exception DeploymentException if an error occurs.
      */
     TypeDeployer createDeployer( ClassLoader loader )
@@ -36,13 +38,17 @@ public interface Deployer
      * necessary.
      *
      * @param file the file containing the type library.
+     * @return the deployer for this type library.
      * @exception DeploymentException if an error occurs.
      */
     TypeDeployer createDeployer( File file )
         throws DeploymentException;
 
     /**
-     * Creates a child deployer.
+     * Creates a deployer which is a child of this deployer.
+     * @param componentManager the ServiceManager for this component.
+     * @return a child deployer.
+     * @throws ServiceException if an error occurs.
      */
     Deployer createChildDeployer( ServiceManager componentManager )
         throws ServiceException;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/deployer/TypeDefinition.java

@@ -19,6 +19,12 @@ public class TypeDefinition
     private final String m_role;
     private final String m_classname;
 
+    /**
+     * Creates a TypeDefinition
+     * @param name the name of the type
+     * @param roleShorthand the name of the role played by this type
+     * @param className the name of the class implementing this type
+     */
     public TypeDefinition( final String name,
                            final String roleShorthand,
                            final String className )
@@ -29,7 +35,7 @@ public class TypeDefinition
     }
 
     /**
-     * Returns the type's implementation class name.
+     * @return the type's implementation class name.
      */
     public final String getClassname()
     {
@@ -37,7 +43,7 @@ public class TypeDefinition
     }
 
     /**
-     * Returns the type's role.
+     * @return the type's role.
      */
     public final String getRole()
     {
@@ -45,7 +51,7 @@ public class TypeDefinition
     }
 
     /**
-     * Returns the type's name.
+     * @return the type's name.
      */
     public String getName()
     {

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/deployer/TypeDeployer.java

@@ -18,6 +18,8 @@ public interface TypeDeployer
 {
     /**
      * Deploys everything in the type library.
+     * @throws DeploymentException
+     *      If the library cannot be deployed.
      */
     void deployAll()
         throws DeploymentException;
@@ -43,6 +45,9 @@ public interface TypeDeployer
      *
      * @param typeDef
      *      The type definition.
+     *
+     * @throws DeploymentException
+     *      If the type cannot be deployed.
      */
     void deployType( TypeDefinition typeDef )
         throws DeploymentException;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/embeddor/Embeddor.java

@@ -20,6 +20,7 @@ import org.apache.myrmidon.listeners.ProjectListener;
  */
 public interface Embeddor
 {
+    /** Role name for this interface. */
     String ROLE = Embeddor.class.getName();
 
     /**
@@ -30,6 +31,8 @@ public interface Embeddor
      *             project file name.
      * @param parameters The project builder parameters.
      * @return the created Project
+     * @throws Exception If an error occurs creating the Project.
+     *
      * @todo Should location be a URL or will it automatically assume file
      *       unless there is a protocol section like ftp:, file: etc
      * @todo parameters needs more thought put into it.
@@ -42,6 +45,7 @@ public interface Embeddor
      *
      * @param name The shorthand name of the listener.
      * @return the listener.
+     * @throws Exception If the listener could not be created.
      */
     ProjectListener createListener( String name )
         throws Exception;
@@ -51,6 +55,7 @@ public interface Embeddor
      *
      * @param parameters The properties to define in the workspace
      * @return the Workspace
+     * @throws Exception If the workspace could not be created.
      */
     Workspace createWorkspace( Parameters parameters )
         throws Exception;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/executor/ExecutionFrame.java

@@ -19,11 +19,21 @@ import org.apache.myrmidon.interfaces.type.TypeManager;
  */
 public interface ExecutionFrame
 {
+    /** Role name for this interface. */
     String ROLE = ExecutionFrame.class.getName();
 
+    /**
+     * @return The TypeManager to use for creating Tasks.
+     */
     TypeManager getTypeManager();
 
+    /**
+     * @return The logger which is used for execution messages.
+     */
     Logger getLogger();
 
+    /**
+     * @return The TaskContext in which the task is executed.
+     */
     TaskContext getContext();
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/executor/Executor.java

@@ -18,12 +18,14 @@ import org.apache.myrmidon.api.TaskException;
  */
 public interface Executor
 {
+    /** Role name for this interface. */
     String ROLE = Executor.class.getName();
 
     /**
      * execute a task.
      *
      * @param task the configruation data for task
+     * @param frame The frame in which the task is executed.
      * @exception TaskException if an error occurs
      */
     void execute( Configuration task, ExecutionFrame frame )

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/extensions/ExtensionManager.java

@@ -18,5 +18,6 @@ import org.apache.avalon.excalibur.extension.PackageRepository;
 public interface ExtensionManager
     extends PackageRepository
 {
+    /** Role name for this interface. */
     String ROLE = ExtensionManager.class.getName();
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/DefaultNameValidator.java

@@ -82,6 +82,7 @@ public class DefaultNameValidator
      * Creates a valid name based on the supplied string value, removing invalid
      * characters. If no valid characters are present, an exception is thrown.
      * @param baseName the name used to construct the valid name
+     * @return a valid name based on the supplied name.
      * @throws Exception if no valid name could be constructed.
      */
     public String makeValidName( final String baseName ) throws Exception
@@ -113,8 +114,7 @@ public class DefaultNameValidator
     }
 
     /**
-     * Validates the supplied name, failing if it is not.
-     * @throws Exception is the supplied name is not valid.
+     * @see NameValidator
      */
     public void validate( final String name ) throws Exception
     {

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/Dependency.java

@@ -18,17 +18,27 @@ public class Dependency
     private final String m_projectName;
     private final String m_targetName;
 
+    /**
+     * @param projectName The project containing the depended-on target.
+     * @param targetName The name of the depended-on target.
+     */
     public Dependency( final String projectName, final String targetName )
     {
         m_projectName = projectName;
         m_targetName = targetName;
     }
 
+    /**
+     * @return The name of the project containing the depended-on target.
+     */
     public String getProjectName()
     {
         return m_projectName;
     }
 
+    /**
+     * @return The name of the depended-on target.
+     */
     public String getTargetName()
     {
         return m_targetName;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/NameValidator.java

@@ -17,6 +17,7 @@ public interface NameValidator
 {
     /**
      * Validates the supplied name, failing if it is not.
+     * @param name The name to be validated.
      * @throws Exception is the supplied name is not valid.
      */
     void validate( String name ) throws Exception;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/Project.java

@@ -18,9 +18,10 @@ import java.io.File;
  */
 public interface Project
 {
+    /** Role name for this interface. */
     String ROLE = Project.class.getName();
 
-    // the name of currently executing project
+    /** Property which holds the name of currently executing project */
     String PROJECT = "myrmidon.project.name";
 
     // the name of currently executing project
@@ -30,7 +31,7 @@ public interface Project
     //String TARGET           = "myrmidon.target.name";
 
     /**
-     * Returns the project name.
+     * @return the project name.
      *
      * TODO: Determine if projects should carry their own name. Breaks IOC but
      * Can be useful as project files embed own name (or should that be description).

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/Target.java

@@ -23,6 +23,8 @@ public class Target
 
     /**
      * Constructs a target.
+     * @param tasks The task models for all tasks in this target.
+     * @param dependencies The dependencies for executing this target.
      */
     public Target( final Configuration[] tasks,
                    final Dependency[] dependencies )

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/model/TypeLib.java

@@ -27,11 +27,21 @@ public class TypeLib
     //The name of type instance
     private final String m_name;
 
+    /**
+     * Create a import for a complete library.
+     * @param library The name of the library to import.
+     */
     public TypeLib( final String library )
     {
         this( library, null, null );
     }
 
+    /**
+     * Create an import for a single type from a library.
+     * @param library The library containing the type.
+     * @param role The role for the imported type.
+     * @param name The name of the imported type.
+     */
     public TypeLib( final String library, final String role, final String name )
     {
         m_library = library;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/property/PropertyResolver.java

@@ -22,6 +22,7 @@ import org.apache.myrmidon.api.TaskContext;
  */
 public interface PropertyResolver
 {
+    /** Role name for this interface. */
     String ROLE = PropertyResolver.class.getName();
 
     /**

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/role/RoleInfo.java

@@ -23,7 +23,9 @@ public final class RoleInfo
     /**
      * Creates a role definition.
      *
-     * @param name The role name.
+     *
+     * Same as calling <code>RoleInfo( name, null, null, null )</code>
+     * @see #RoleInfo( String, String, Class, String )
      */
     public RoleInfo( final String name )
     {
@@ -33,8 +35,8 @@ public final class RoleInfo
     /**
      * Creates a role definition.
      *
-     * @param name The role name.
-     * @param shorthand The role shorthand name.
+     * Same as calling <code>RoleInfo( name, shorthand, null, null )</code>
+     * @see #RoleInfo( String, String, Class, String )
      */
     public RoleInfo( final String name, final String shorthand )
     {
@@ -43,10 +45,8 @@ public final class RoleInfo
 
     /**
      * Creates a role definition.
-     *
-     * @param name The role name.
-     * @param shorthand The role shorthand name.  May be null.
-     * @param type The role type.  May be null.
+     * Same as calling <code>RoleInfo( name, shorthand, type, null )</code>
+     * @see #RoleInfo( String, String, Class, String )
      */
     public RoleInfo( final String name, final String shorthand, final Class type )
     {
@@ -56,6 +56,8 @@ public final class RoleInfo
     /**
      * Creates a role definition.  The role type's fully-qualified name
      * is used as the role name.
+     *
+     * @see #RoleInfo( String, String, Class, String )
      */
     public RoleInfo( final String shorthand, final Class type )
     {
@@ -64,6 +66,10 @@ public final class RoleInfo
 
     /**
      * Creates a role definition.
+     * @param name The role name.
+     * @param shorthand The role shorthand name.  May be null.
+     * @param type The role type.  May be null.
+     * @param defaultType The default type to use. May be null.
      */
     public RoleInfo( final String name,
                      final String shorthand,
@@ -78,6 +84,8 @@ public final class RoleInfo
 
     /**
      * Compares a role to this role.
+     * @param role The RoleInfo to compare.
+     * @return <code>true</code> if the supplied role is equal to this one.
      */
     public boolean equals( final RoleInfo role )
     {
@@ -105,7 +113,8 @@ public final class RoleInfo
     }
 
     /**
-     * Returns this role's name.  This name uniquely identifies the role.
+     * Provides this role's name, which uniquely identifies the role.
+     * @return The role name.
      */
     public String getName()
     {

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/role/RoleManager.java

@@ -19,6 +19,7 @@ package org.apache.myrmidon.interfaces.role;
  */
 public interface RoleManager
 {
+    /** Role name for this interface. */
     String ROLE = RoleManager.class.getName();
 
     /**
@@ -47,6 +48,8 @@ public interface RoleManager
 
     /**
      * Adds a role definition.
+     * @param role The RoleInfo definition of the role to add.
+     * @throws RoleException If this role conflict with an existing role.
      */
     void addRole( RoleInfo role ) throws RoleException;
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/service/MultiSourceServiceManager.java

@@ -31,6 +31,7 @@ public class MultiSourceServiceManager
 
     /**
      * Adds a service manager to the end of the source list.
+     * @param mgr The ServiceManager to add.
      */
     public void add( final ServiceManager mgr )
     {
@@ -39,6 +40,9 @@ public class MultiSourceServiceManager
 
     /**
      * Determines if this service manager contains a particular service.
+     * @param serviceRole The name of the service to check for.
+     * @return <code>true</code> if this service manager contains
+     *         the named service.
      */
     public boolean hasService( final String serviceRole )
     {
@@ -81,6 +85,7 @@ public class MultiSourceServiceManager
 
     /**
      * Releases a service.
+     * @param service The service to release.
      */
     public void release( final Object service )
     {

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/service/ServiceFactory.java

@@ -19,12 +19,15 @@ package org.apache.myrmidon.interfaces.service;
  */
 public interface ServiceFactory
 {
+    /** Role name for this interface. */
     String ROLE = ServiceFactory.class.getName();
 
     /**
      * Create a service that corresponds to this factory.
      * This method is usually called after the factory has been
      * prepared and configured as appropriate.
+     * @return The created service.
+     * @throws AntServiceException If the service could not be created.
      */
     Object createService()
         throws AntServiceException;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/type/DefaultTypeFactory.java

@@ -32,6 +32,7 @@ public class DefaultTypeFactory
     /**
      * Construct a factory that uses specified ClassLoader to load
      * types from.
+     * @param classLoader The ClassLoader to use for loading types.
      */
     public DefaultTypeFactory( final ClassLoader classLoader )
     {
@@ -52,6 +53,8 @@ public class DefaultTypeFactory
 
     /**
      * Map a name to the fully qualified name of the Class that implements type.
+     * @param name The type name.
+     * @param className The fully qualified name of the implementin Class.
      */
     public void addNameClassMapping( final String name, final String className )
     {
@@ -59,7 +62,7 @@ public class DefaultTypeFactory
     }
 
     /**
-     * Determines if this factory can create instances of a particular type.
+     * @see TypeFactory#canCreate
      */
     public boolean canCreate( String name )
     {
@@ -67,11 +70,7 @@ public class DefaultTypeFactory
     }
 
     /**
-     * Create a type instance with appropriate name.
-     *
-     * @param name the name
-     * @return the created instance
-     * @exception TypeException if an error occurs
+     * @see TypeFactory#create
      */
     public Object create( final String name )
         throws TypeException
@@ -103,6 +102,9 @@ public class DefaultTypeFactory
         return (String)m_classNames.get( name );
     }
 
+    /**
+     * @return The ClassLoader to use for loading types.
+     */
     protected ClassLoader getClassLoader()
     {
         return m_classLoader;

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/type/ReloadingTypeFactory.java

@@ -35,6 +35,10 @@ public class ReloadingTypeFactory
      * Construct a factory that recreats a ClassLoader from specified
      * URLs and with specified parent ClassLoader. The specified urls must
      * not be null.
+     * @param urls
+     *      The URLs to include in the created classloader.
+     * @param parent
+     *      The parent to use for the created classloader. May be null.
      */
     public ReloadingTypeFactory( final URL[] urls,
                                  final ClassLoader parent )
@@ -47,6 +51,9 @@ public class ReloadingTypeFactory
         m_parent = parent;
     }
 
+    /**
+     * @see DefaultTypeFactory
+     */
     protected ClassLoader getClassLoader()
     {
         return new URLClassLoader( m_urls, m_parent );

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/type/TypeFactory.java

@@ -19,6 +19,7 @@ public interface TypeFactory
      * Determines if this factory can create instances of a particular type.
      *
      * @param name the type name.
+     * @return <code>true</code> if this is a valid factory for the named type.
      */
     boolean canCreate( String name );
 

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/type/TypeManager.java

@@ -15,6 +15,7 @@ package org.apache.myrmidon.interfaces.type;
  */
 public interface TypeManager
 {
+    /** Role name for this interface. */
     String ROLE = TypeManager.class.getName();
 
     /**
@@ -23,6 +24,7 @@ public interface TypeManager
      * @param roleName The role for the type.
      * @param shorthandName The shorthand name for the type.
      * @param factory The type factory.
+     * @throws TypeException If an error occurs.
      */
     void registerType( String roleName, String shorthandName, TypeFactory factory )
         throws TypeException;
@@ -31,6 +33,8 @@ public interface TypeManager
      * Returns the factory for a role.
      *
      * @param roleName The role for the type.
+     * @return The TypeFactory for the named role.
+     * @throws TypeException If the rolename is invalid.
      */
     TypeFactory getFactory( String roleName )
         throws TypeException;
@@ -39,6 +43,7 @@ public interface TypeManager
      * Creates a child type manager.  The child inherits the type factories
      * from this type manager.  Additional type factories may be added to the
      * child, without affecting this type manager.
+     * @return A TypeManager with this as it's parent.
      */
     TypeManager createChildTypeManager();
 }

proposal/myrmidon/src/java/org/apache/myrmidon/interfaces/workspace/Workspace.java

@@ -19,6 +19,7 @@ import org.apache.myrmidon.listeners.ProjectListener;
  */
 public interface Workspace
 {
+    /** Role name for this interface. */
     String ROLE = Workspace.class.getName();
 
     /**