javadoc/formatting/protected constructors for abstract classes

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

src/main/org/apache/tools/ant/types/resources/ArchiveResource.java

@@ -42,7 +42,7 @@ public abstract class ArchiveResource extends Resource {
     /**
      * Default constructor.
      */
-    public ArchiveResource() {
+    protected ArchiveResource() {
     }
 
     /**
@@ -50,7 +50,7 @@ public abstract class ArchiveResource extends Resource {
      * entry in the specified archive.
      * @param a the archive as File.
      */
-    public ArchiveResource(File a) {
+    protected ArchiveResource(File a) {
         this(a, false);
     }
 
@@ -60,7 +60,7 @@ public abstract class ArchiveResource extends Resource {
      * @param a the archive as File.
      * @param withEntry if the entry has been specified.
      */
-    public ArchiveResource(File a, boolean withEntry) {
+    protected ArchiveResource(File a, boolean withEntry) {
         setArchive(a);
         haveEntry = withEntry;
     }
@@ -71,7 +71,7 @@ public abstract class ArchiveResource extends Resource {
      * @param a the archive as Resource.
      * @param withEntry if the entry has been specified.
      */
-    public ArchiveResource(Resource a, boolean withEntry) {
+    protected ArchiveResource(Resource a, boolean withEntry) {
         addConfigured(a);
         haveEntry = withEntry;
     }
@@ -242,6 +242,10 @@ public abstract class ArchiveResource extends Resource {
             : getArchive().toString() + ':' + getName();
     }
 
+    /**
+     * Validate settings and ensure that the represented "archive entry"
+     * has been established.  
+     */
     protected final synchronized void checkEntry() throws BuildException {
         dieOnCircularReference();
         if (haveEntry) {
@@ -266,10 +270,13 @@ public abstract class ArchiveResource extends Resource {
     }
 
     /**
-     * fetches information from the named entry inside the archive.
+     * Fetch information from the named entry inside the archive.
      */
     protected abstract void fetchEntry();
 
+    /**
+     * {@inheritDoc}
+     */
     protected synchronized void dieOnCircularReference(Stack stk, Project p) {
         if (isChecked()) {
             return;

src/main/org/apache/tools/ant/types/resources/CompressedResource.java

@@ -31,14 +31,14 @@ import org.apache.tools.ant.types.ResourceCollection;
 public abstract class CompressedResource extends ContentTransformingResource {
 
     /** no arg constructor */
-    public CompressedResource() {
+    protected CompressedResource() {
     }
 
     /**
      * Constructor with another resource to wrap.
      * @param other the resource to wrap.
      */
-    public CompressedResource(ResourceCollection other) {
+    protected CompressedResource(ResourceCollection other) {
         addConfigured(other);
     }
 

src/main/org/apache/tools/ant/types/resources/ContentTransformingResource.java

@@ -26,7 +26,7 @@ import org.apache.tools.ant.types.ResourceCollection;
 import org.apache.tools.ant.util.FileUtils;
 
 /**
- * A compressed resource.
+ * A resource that transforms the content of another resource.
  *
  * <p>Wraps around another resource, delegates all queries (except
  * getSize) to that other resource but transforms stream content
@@ -39,14 +39,14 @@ public abstract class ContentTransformingResource extends ResourceDecorator {
     private static final int BUFFER_SIZE = 8192;
 
     /** no arg constructor */
-    public ContentTransformingResource() {
+    protected ContentTransformingResource() {
     }
 
     /**
      * Constructor with another resource to wrap.
      * @param other the resource to wrap.
      */
-    public ContentTransformingResource(ResourceCollection other) {
+    protected ContentTransformingResource(ResourceCollection other) {
         super(other);
     }
 
@@ -121,7 +121,7 @@ public abstract class ContentTransformingResource extends ResourceDecorator {
                 if (a != null) {
                     return new Appendable() {
                         public OutputStream getAppendOutputStream()
-                            throws IOException {
+                                throws IOException {
                             OutputStream out = a.getAppendOutputStream();
                             if (out != null) {
                                 out = wrapStream(out);
@@ -139,7 +139,7 @@ public abstract class ContentTransformingResource extends ResourceDecorator {
     }
 
     /**
-     * whether the transformation performed allows appends.
+     * Learn whether the transformation performed allows appends.
      *
      * <p>In general compressed outputs will become invalid if they
      * are appended to, for example.</p>
@@ -151,7 +151,7 @@ public abstract class ContentTransformingResource extends ResourceDecorator {
     }    
 
     /**
-     * Is supposed to wrap the stream.
+     * Get a content-filtering/transforming InputStream.
      *
      * @param in InputStream to wrap, will never be null.
      * @return a compressed inputstream.
@@ -161,7 +161,7 @@ public abstract class ContentTransformingResource extends ResourceDecorator {
         throws IOException;
 
     /**
-     * Is supposed to wrap the stream to allow transformation on the fly.
+     * Get a content-filtering/transforming OutputStream.
      *
      * @param out OutputStream to wrap, will never be null.
      * @return a compressed outputstream.

src/main/org/apache/tools/ant/types/resources/JavaConstantResource.java

@@ -25,8 +25,7 @@ import java.lang.reflect.Field;
 /**
  * A resource that is a java constant.
  * This lets you extract values off the classpath and use them elsewhere
- * @since Ant1.7
- *
+ * @since Ant 1.7
  */
 
 public class JavaConstantResource extends AbstractClasspathResource {
@@ -67,5 +66,4 @@ public class JavaConstantResource extends AbstractClasspathResource {
         }
     }
 
-
 }

src/main/org/apache/tools/ant/types/resources/MappedResource.java

@@ -35,6 +35,8 @@ public class MappedResource extends ResourceDecorator {
 
     /**
      * Wraps an existing resource.
+     * @param r Resource to wrap
+     * @param m FileNameMapper that handles mapping
      */
     public MappedResource(Resource r, FileNameMapper m) {
         super(r);
@@ -48,14 +50,14 @@ public class MappedResource extends ResourceDecorator {
         String name = getResource().getName();
         if (isReference()) {
             return name;
-        } else {
-            String[] mapped = mapper.mapFileName(name);
-            return mapped != null && mapped.length > 0 ? mapped[0] : null;
         }
+        String[] mapped = mapper.mapFileName(name);
+        return mapped != null && mapped.length > 0 ? mapped[0] : null;
     }
 
     /**
      * Not really supported since mapper is never null.
+     * @param r reference to set
      */
     public void setRefid(Reference r) {
         if (mapper != null) {
@@ -66,10 +68,11 @@ public class MappedResource extends ResourceDecorator {
 
     /**
      * Suppress FileProvider
+     * @param clazz the type to implement
      */
     public Object as(Class clazz) {
         return FileProvider.class.isAssignableFrom(clazz) 
-            ? null : getResource().as(clazz);
+                ? null : getResource().as(clazz);
     }
 
-}
+}

src/main/org/apache/tools/ant/types/resources/MappedResourceCollection.java

@@ -35,7 +35,7 @@ import org.apache.tools.ant.util.IdentityMapper;
  * @since Ant 1.8.0
  */
 public class MappedResourceCollection
-    extends DataType implements ResourceCollection, Cloneable {
+        extends DataType implements ResourceCollection, Cloneable {
 
     private ResourceCollection nested = null;
     private Mapper mapper = null;
@@ -86,7 +86,7 @@ public class MappedResourceCollection
     }
 
     /**
-     * @return false
+     * {@inheritDoc}
      */
     public boolean isFilesystemOnly() {
         if (isReference()) {
@@ -98,7 +98,7 @@ public class MappedResourceCollection
     }
 
     /**
-     * @return size of the nested resource collection.
+     * {@inheritDoc}
      */
     public int size() {
         if (isReference()) {
@@ -108,6 +108,9 @@ public class MappedResourceCollection
         return nested.size();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Iterator iterator() {
         if (isReference()) {
             return ((MappedResourceCollection) getCheckedRef()).iterator();
@@ -128,8 +131,7 @@ public class MappedResourceCollection
     }
 
     /**
-     * Implement clone.  The nested resource collection and mapper are
-     * copied.
+     * Implement clone.  The nested resource collection and mapper are copied.
      * @return a cloned instance.
      */
     public Object clone() {
@@ -204,4 +206,4 @@ public class MappedResourceCollection
             throw new UnsupportedOperationException();
         }
     }
-}
+}