creadur-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r1374634 - in /creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis: LicenseAnalyst.java ResourceDefinitionError.java ResourceDefinitionException.java ResourceDescription.java
Date Sat, 18 Aug 2012 18:57:44 GMT
Author: rdonkin
Date: Sat Aug 18 18:57:44 2012
New Revision: 1374634

URL: http://svn.apache.org/viewvc?rev=1374634&view=rev
Log:
Improved javadocs based on checkstyle

Modified:
    creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/LicenseAnalyst.java
    creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionError.java
    creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionException.java
    creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDescription.java

Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/LicenseAnalyst.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/LicenseAnalyst.java?rev=1374634&r1=1374633&r2=1374634&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/LicenseAnalyst.java
(original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/LicenseAnalyst.java
Sat Aug 18 18:57:44 2012
@@ -14,7 +14,7 @@
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
- * under the License. 
+ * under the License.
  */
 package org.apache.creadur.whisker.app.analysis;
 
@@ -31,15 +31,20 @@ import org.apache.creadur.whisker.model.
 import org.apache.creadur.whisker.scan.Directory;
 
 /**
- * 
+ * Analyses licenses.
  */
 public class LicenseAnalyst {
-    
+
     /**
-     * @return
+     * Maps issues.
+     * @return not null
      */
-    private static Map<ResourceDefinitionError, Collection<ResourceDescription>>
buildIssueMap() {
-        final Map<ResourceDefinitionError, Collection<ResourceDescription>> results
= new HashMap<ResourceDefinitionError, Collection<ResourceDescription>>();
+    private static Map<ResourceDefinitionError,
+                        Collection<ResourceDescription>> buildIssueMap() {
+        final Map<ResourceDefinitionError,
+                    Collection<ResourceDescription>> results =
+                    new HashMap<ResourceDefinitionError,
+                        Collection<ResourceDescription>>();
         for (final ResourceDefinitionError error: ResourceDefinitionError.values()) {
             initIssues(results, error);
         }
@@ -47,8 +52,9 @@ public class LicenseAnalyst {
     }
 
     /**
-     * @param results
-     * @param error
+     * Builds an initial map.
+     * @param results not null
+     * @param error not null
      */
     private static void initIssues(
             final Map<ResourceDefinitionError, Collection<ResourceDescription>>
results,
@@ -56,41 +62,55 @@ public class LicenseAnalyst {
         results.put(error, new TreeSet<ResourceDescription>());
     }
 
-    
+    /** Directories analysed. */
     private final Collection<Directory> directories;
-    private final Map<ResourceDefinitionError, Collection<ResourceDescription>>
issues;
-    
+    /** Maps resource errors to resources. */
+    private final Map<ResourceDefinitionError,
+                    Collection<ResourceDescription>> issues;
+
+    /**
+     * Constructs empty analyst.
+     */
     public LicenseAnalyst() {
         this(null);
     }
-    
+
     /**
-     * @param work
-     * @param directories
+     * Analyse the given directories.
+     * @param directories, not null
      */
-    public LicenseAnalyst(Collection<Directory> directories) {
+    public LicenseAnalyst(final Collection<Directory> directories) {
         super();
         this.directories = directories;
         issues = buildIssueMap();
     }
 
+    /**
+     * Discover discrepancies between meta-data and source directories.
+     * @param work not null
+     * @return this, not null
+     */
     public LicenseAnalyst analyse(final Descriptor work) {
         if (directories == null) {
-            final ResourceNamesCollator collator = new ResourceNamesCollator();
+            final ResourceNamesCollator collator =
+                    new ResourceNamesCollator();
             work.traverse(collator);
             analyseDuplicates(collator);
-            
-            final ResourceSourceAuditor sourceAuditor = new ResourceSourceAuditor();
+
+            final ResourceSourceAuditor sourceAuditor =
+                    new ResourceSourceAuditor();
             work.traverse(sourceAuditor);
             analyse(sourceAuditor);
         } else {
             for (final Directory directory: directories) {
-                final ResourceNamesCollator collator = new ResourceNamesCollator();
+                final ResourceNamesCollator collator =
+                        new ResourceNamesCollator();
                 work.traverseDirectory(collator, directory.getName());
                 analyseLicenses(directory, collator);
                 analyseDuplicates(collator);
-                
-                final ResourceSourceAuditor sourceAuditor = new ResourceSourceAuditor();
+
+                final ResourceSourceAuditor sourceAuditor = new
+                        ResourceSourceAuditor();
                 work.traverseDirectory(sourceAuditor, directory.getName());
                 analyse(sourceAuditor);
             }
@@ -99,60 +119,92 @@ public class LicenseAnalyst {
     }
 
     /**
-     * @param sourceAuditor
+     * Analyse the directories with this auditor.
+     * @param sourceAuditor not null
      */
-    private void analyse(ResourceSourceAuditor sourceAuditor) {
-        addIssues(sourceAuditor.getResourcesMissingSource(), ResourceDefinitionError.MISSING_SOURCE);
+    private void analyse(final ResourceSourceAuditor sourceAuditor) {
+        addIssues(sourceAuditor.getResourcesMissingSource(),
+                ResourceDefinitionError.MISSING_SOURCE);
     }
 
+    /**
+     * Were any errors found?
+     * @return true when the meta-data is valid,
+     * false otherwise
+     */
     public boolean isValid() {
-        for (final ResourceDefinitionError error: ResourceDefinitionError.values()) {
+        for (final ResourceDefinitionError error:
+                ResourceDefinitionError.values()) {
             if (!getIssues(error).isEmpty()) {
                 return false;
             }
         }
         return true;
     }
-    
-    public Descriptor validate(final Descriptor work) throws ResourceDefinitionException
{
+
+    /**
+     * Checks the descriptor against the source directories.
+     * @param work not null
+     * @return valid meta-data
+     * @throws ResourceDefinitionException when issues are found
+     */
+    public Descriptor validate(final Descriptor work)
+            throws ResourceDefinitionException {
         analyse(work);
         if (isValid()) {
             return work;
         } else {
             throw new ResourceDefinitionException(issues);
         }
-            
+
     }
-    
+
     /**
-     * @param collator
+     * Discovers duplicates.
+     * @param collator not null
      */
-    private void analyseDuplicates(final ResourceNamesCollator collator) {
-        addIssues(collator.getDuplicates(), ResourceDefinitionError.DUPLICATE);
+    private void analyseDuplicates(
+            final ResourceNamesCollator collator) {
+        addIssues(collator.getDuplicates(),
+                ResourceDefinitionError.DUPLICATE);
     }
 
     /**
-     * @param resources
-     * @param error
+     * Adds the issues to the store.
+     * @param resources not null
+     * @param error not null
      */
     private void addIssues(
-            Collection<Pair<org.apache.creadur.whisker.model.WithinDirectory, Resource>>
resources,
-            ResourceDefinitionError error) {
-        for (Pair<org.apache.creadur.whisker.model.WithinDirectory, Resource> duplicate:
resources) {
-            getIssues(error).add(new ResourceDescription(duplicate.getLeft().getName(), duplicate.getRight().getName()));
+            final Collection<Pair<
+                org.apache.creadur.whisker.model.WithinDirectory,
+                Resource>> resources,
+            final ResourceDefinitionError error) {
+        for (Pair<
+                org.apache.creadur.whisker.model.WithinDirectory,
+                Resource> duplicate: resources) {
+            getIssues(error).add(
+                    new ResourceDescription(
+                            duplicate.getLeft().getName(),
+                            duplicate.getRight().getName()));
         }
     }
 
+    /**
+     * Checks for too many or few licenses.
+     * @param directory not null
+     * @param collator not null
+     */
     private void analyseLicenses(final Directory directory,
             final ResourceNamesCollator collator) {
         analyseExtraLicenses(directory, collator);
         analyseMissingLicenses(directory, collator);
     }
 
-    
+
     /**
-     * @param directory
-     * @param collator
+     * Checks for to many licenses.
+     * @param directory not null
+     * @param collator not null
      */
     @SuppressWarnings("PMD.EmptyIfStmt")
     private void analyseExtraLicenses(final Directory directory,
@@ -162,14 +214,18 @@ public class LicenseAnalyst {
             if (actualResources.contains(resourceLicense)) {
                 // Fine
             } else {
-                getExtraLicenses().add(new ResourceDescription(directory.getName(), resourceLicense));
+                getExtraLicenses().add(
+                        new ResourceDescription(
+                                directory.getName(),
+                                resourceLicense));
             }
         }
     }
-    
+
     /**
-     * @param directory
-     * @param collator
+     * Checks for too few licenses.
+     * @param directory not null
+     * @param collator not null
      */
     @SuppressWarnings("PMD.EmptyIfStmt")
     private void analyseMissingLicenses(final Directory directory,
@@ -179,42 +235,63 @@ public class LicenseAnalyst {
             if (licensedResources.contains(actualResource)) {
                 // Fine
             } else {
-                getMissingLicenses().add(new ResourceDescription(directory.getName(), actualResource));
+                getMissingLicenses().add(
+                        new ResourceDescription(
+                                directory.getName(),
+                                actualResource));
             }
         }
     }
 
-
+    /**
+     * Gets resources whose sources are missing.
+     * @return not null, possibly empty
+     */
     public Collection<ResourceDescription> getResourcesMissingSources() {
         return getIssues(ResourceDefinitionError.MISSING_SOURCE);
     }
 
-    
-    
+    /**
+     * Gets surplus licenses.
+     * @return not null, possibly empty
+     */
     public Collection<ResourceDescription> getExtraLicenses() {
         return getIssues(ResourceDefinitionError.EXTRA_LICENSE);
     }
-    
+
+    /**
+     * Gets missing license.
+     * @return not null, possibly empty
+     */
     public Collection<ResourceDescription> getMissingLicenses() {
         return getIssues(ResourceDefinitionError.MISSING_LICENSE);
     }
-    
+
     /**
+     * Gets duplicate resources.
      * @return the duplicates
      */
     public Collection<ResourceDescription> getDuplicates() {
         return getIssues(ResourceDefinitionError.DUPLICATE);
     }
 
-    public Collection<ResourceDescription> getIssues(ResourceDefinitionError ofType)
{
+    /**
+     * Gets issues by type.
+     * @param ofType not null
+     * @return issues of given type, not null, possibly empty
+     */
+    public Collection<ResourceDescription> getIssues(
+            ResourceDefinitionError ofType) {
         return issues.get(ofType);
     }
-    
+
     /**
+     * Describes suitably for logging.
+     * @return something suitable for logging
      * @see java.lang.Object#toString()
      */
     @Override
     public String toString() {
         return "LicenseAnalyst [directories=" + directories + "]";
     }
-}
+}
\ No newline at end of file

Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionError.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionError.java?rev=1374634&r1=1374633&r2=1374634&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionError.java
(original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionError.java
Sat Aug 18 18:57:44 2012
@@ -14,23 +14,39 @@
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
- * under the License. 
+ * under the License.
  */
 package org.apache.creadur.whisker.app.analysis;
 
+/**
+ * Enumerates modes of definitional error.
+ */
 public enum ResourceDefinitionError {
+    /** Expected license definition is missing. */
     MISSING_LICENSE("Missing license(s)"),
+    /** Duplicate licenses */
     EXTRA_LICENSE("Extra license(s)"),
+    /** Duplicate resources.  */
     DUPLICATE("Duplicate resource(s)"),
+    /** Links to source is missing. */
     MISSING_SOURCE("Missing link to source ");
-    
+
+    /** Describes this error suitable for display. */
     private final String description;
-    
-    private ResourceDefinitionError (final String description) {
+
+    /**
+     * Constructs an error with the given description.
+     * @param description not null
+     */
+    private ResourceDefinitionError(final String description) {
         this.description = description;
     }
-    
-    public String getDescription() {
+
+    /**
+     * Gets a description suitable for display.
+     * @return not null
+     */
+    public final String getDescription() {
         return description;
     }
-}
\ No newline at end of file
+}

Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionException.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionException.java?rev=1374634&r1=1374633&r2=1374634&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionException.java
(original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDefinitionException.java
Sat Aug 18 18:57:44 2012
@@ -14,7 +14,7 @@
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
- * under the License. 
+ * under the License.
  */
 package org.apache.creadur.whisker.app.analysis;
 
@@ -22,10 +22,22 @@ import java.util.Collection;
 import java.util.Collections;
 import java.util.Map;
 
+/**
+ * Indicates an issue with a resource definition.
+ */
 public final class ResourceDefinitionException extends Exception {
 
-    private static String message(final Map<ResourceDefinitionError, Collection<ResourceDescription>>
issues) {
-        final StringBuilder builder = new StringBuilder("Resources definitions are incorrect.
");
+    /**
+     * Composes an informative error message.
+     * @param issues not null
+     * @return informative error message, not null
+     */
+    private static String message(
+            final Map<
+                ResourceDefinitionError,
+                Collection<ResourceDescription>> issues) {
+        final StringBuilder builder =
+                new StringBuilder("Resources definitions are incorrect. ");
         for (ResourceDefinitionError error: issues.keySet()) {
             if (!issues.get(error).isEmpty()) {
                 builder.append(error.getDescription()).append(": ");
@@ -36,7 +48,10 @@ public final class ResourceDefinitionExc
                     } else {
                         builder.append("; ");
                     }
-                    builder.append(description.getResource()).append(" in ").append(description.getDirectory());
+                    builder
+                        .append(description.getResource())
+                        .append(" in ")
+                        .append(description.getDirectory());
                 }
                 builder.append(". ");
             }
@@ -44,22 +59,34 @@ public final class ResourceDefinitionExc
         return builder.toString();
     }
 
+    /** For serialisation. */
     private static final long serialVersionUID = -455455829914484243L;
-    
-    private final Map<ResourceDefinitionError, Collection<ResourceDescription>>
issues;
-    
+
+    /**
+     * Causal issues.
+     */
+    private final Map<
+        ResourceDefinitionError,
+        Collection<ResourceDescription>> issues;
+
     /**
-     * @param duplicates
+     * Constructs an exception caused by the given issues.
+     * @param issues not null
      */
-    public ResourceDefinitionException(Map<ResourceDefinitionError, Collection<ResourceDescription>>
issues) {
+    public ResourceDefinitionException(
+            final Map<ResourceDefinitionError,
+            Collection<ResourceDescription>> issues) {
         super(message(issues));
         this.issues = Collections.unmodifiableMap(issues);
     }
 
     /**
-     * @return the issues
+     * Gets causal issues.
+     * @return the issues not null
      */
-    public Map<ResourceDefinitionError, Collection<ResourceDescription>> getIssues()
{
+    public Map<
+                ResourceDefinitionError,
+                Collection<ResourceDescription>> getIssues() {
         return issues;
     }
 }
\ No newline at end of file

Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDescription.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDescription.java?rev=1374634&r1=1374633&r2=1374634&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDescription.java
(original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/analysis/ResourceDescription.java
Sat Aug 18 18:57:44 2012
@@ -14,39 +14,50 @@
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
- * under the License. 
+ * under the License.
  */
 package org.apache.creadur.whisker.app.analysis;
 
+/**
+ * Describes a resource in a software distribution.
+ */
 public class ResourceDescription implements Comparable<ResourceDescription> {
+    /** Containing directory. */
     private final String directory;
+    /** Resource name. */
     private final String resource;
-    
+
     /**
-     * @param directoryName
-     * @param resourceName
+     * Constructs a description of the given resource.
+     * @param directoryName not null
+     * @param resourceName not null
      */
-    public ResourceDescription(String directoryName, String resourceName) {
+    public ResourceDescription(
+            final String directoryName, final String resourceName) {
         super();
         this.directory = directoryName;
         this.resource = resourceName;
     }
 
     /**
-     * @return the directoryName
+     * Gets the name of the containing directory.
+     * @return the directoryName, not null
      */
-    public String getDirectory() {
+    public final String getDirectory() {
         return directory;
     }
 
     /**
-     * @return the resourceName
+     * Gets the resource name.
+     * @return the resourceName, not null
      */
-    public String getResource() {
+    public final String getResource() {
         return resource;
     }
 
     /**
+     * Hash code compatible with equals.
+     * @return a suitable hash code
      * @see java.lang.Object#hashCode()
      */
     @Override
@@ -61,31 +72,43 @@ public class ResourceDescription impleme
     }
 
     /**
+     * Equal means identical name and directory.
+     * @param obj object to be compared against
+     * @return true when equal
      * @see java.lang.Object#equals(java.lang.Object)
      */
     @Override
-    public boolean equals(Object obj) {
-        if (this == obj)
+    public boolean equals(final Object obj) {
+        if (this == obj) {
             return true;
-        if (obj == null)
+        }
+        if (obj == null) {
             return false;
-        if (getClass() != obj.getClass())
+        }
+        if (getClass() != obj.getClass()) {
             return false;
-        ResourceDescription other = (ResourceDescription) obj;
+        }
+        final ResourceDescription other = (ResourceDescription) obj;
         if (directory == null) {
-            if (other.directory != null)
+            if (other.directory != null) {
                 return false;
-        } else if (!directory.equals(other.directory))
+            }
+        } else if (!directory.equals(other.directory)) {
             return false;
+        }
         if (resource == null) {
-            if (other.resource != null)
+            if (other.resource != null) {
                 return false;
-        } else if (!resource.equals(other.resource))
+            }
+        } else if (!resource.equals(other.resource)) {
             return false;
+        }
         return true;
     }
 
     /**
+     * Suitable for logging.
+     * @return not null
      * @see java.lang.Object#toString()
      */
     @Override
@@ -95,9 +118,12 @@ public class ResourceDescription impleme
     }
 
     /**
+     * Natural comparison is directory name, then resource name.
+     * @param other possibly null
+     * @return numeric comparison
      * @see java.lang.Comparable#compareTo(java.lang.Object)
      */
-    public int compareTo(ResourceDescription other) {
+    public int compareTo(final ResourceDescription other) {
         final int result;
         final int compareOnDirectoryName = this.getDirectory().compareTo(other.getDirectory());
         if (compareOnDirectoryName == 0) {
@@ -107,6 +133,6 @@ public class ResourceDescription impleme
         }
         return result;
     }
-    
-    
+
+
 }
\ No newline at end of file



Mime
View raw message