creadur-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r1340729 - in /creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model: ByOrganisation.java Descriptor.java License.java LicenseAndOrganisationCollator.java LicenseTemplateException.java Organisation.java
Date Sun, 20 May 2012 14:11:42 GMT
Author: rdonkin
Date: Sun May 20 14:11:42 2012
New Revision: 1340729

URL: http://svn.apache.org/viewvc?rev=1340729&view=rev
Log:
Added some documentation

Modified:
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/ByOrganisation.java
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Descriptor.java
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/License.java
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseAndOrganisationCollator.java
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseTemplateException.java
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Organisation.java

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/ByOrganisation.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/ByOrganisation.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/ByOrganisation.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/ByOrganisation.java
Sun May 20 14:11:42 2012
@@ -21,14 +21,19 @@ package org.apache.creadur.whisker.model
 import java.util.Collection;
 
 /**
- * 
+ * Relates the responsible group or individual to one
+ * or more resources.
  */
 public class ByOrganisation implements Comparable<ByOrganisation> {
 
+    /** The responsible group or individual. */
     private final Organisation organisation;
+    /** The resources for which the group or individual is responsible. */
     private final Collection<Resource> resources;
 
     /**
+     * Links an individual or group
+     * to the resources for which they have responsibility.
      * @param resources
      *            not null
      * @param organisation
@@ -41,34 +46,54 @@ public class ByOrganisation implements C
         this.resources = resources;
     }
 
+    /**
+     * Gets the name of the individual or group responsible.
+     * @return not null
+     */
     public String getName() {
         return this.organisation.getName();
     }
 
+    /**
+     * Gets the primary URL for the individual or group responsible.
+     * @return not null
+     */
     public String getURL() {
         return this.organisation.getURL();
     }
 
+    /**
+     * Gets the primary identifier for the individual or group responsible.
+     * @return not null
+     */
     public String getId() {
         return this.organisation.getId();
     }
 
+    /**
+     * Gets the resource for which the linked individual or group is responsible.
+     * @return not null, possibly empty
+     */
     public Collection<Resource> getResources() {
         return this.resources;
     }
 
     /**
-     * @return the organisation
+     * Gets the organisation representing the individual or group responible
+     * for the linked resources.
+     * @return the organisation , not ull
      */
     public Organisation getOrganisation() {
         return this.organisation;
     }
 
     /**
+     * Based on organisation.
      * @see java.lang.Object#hashCode()
+     * @return hash based on organisation
      */
     @Override
-    public int hashCode() {
+    public final int hashCode() {
         final int prime = 31;
         int result = 1;
         result = prime
@@ -79,7 +104,11 @@ public class ByOrganisation implements C
     }
 
     /**
+     * Equal iff organisations are equal.
      * @see java.lang.Object#equals(java.lang.Object)
+     * @param obj possibly null
+     * @return true when organisations are equal,
+     * false otherwise
      */
     @Override
     public boolean equals(final Object obj) {
@@ -104,14 +133,18 @@ public class ByOrganisation implements C
     }
 
     /**
+     * Delegates to organisation.
      * @see java.lang.Comparable#compareTo(java.lang.Object)
+     * @param other possibly null
+     * @return {@link Organisation#compareTo(Organisation)}
      */
     public int compareTo(final ByOrganisation other) {
         return this.organisation.compareTo(other.getOrganisation());
     }
 
     /**
-     * @param visitor
+     * Accepts a visitor.
+     * @param visitor possibly null
      */
     public void accept(final Visitor visitor) {
         if (visitor != null && visitor.traverseByOrganisation()) {
@@ -121,7 +154,11 @@ public class ByOrganisation implements C
             }
         }
     }
-
+    
+    /**
+     * Describes object suitably for logging.
+     * @return something suitable for logging
+     */
     @Override
     public String toString() {
         return "ByOrganisation [organisation=" + this.organisation

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Descriptor.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Descriptor.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Descriptor.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Descriptor.java
Sun May 20 14:11:42 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.model;
 
@@ -23,17 +23,34 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * 
+ * High level description of licensing qualities.
  */
 public class Descriptor {
 
+    /** Principle license for main work. */
     private final License primaryLicense;
+    /** Individual or group with main responsible for main work. */
     private final String primaryOrganisationId;
+    /** A NOTICE for the main work, for inclusion alongside the LICENSE.*/
     private final String primaryNotice;
+    /** License meta-data, indexed by id. */
     private final Map<String, License> licenses;
+    /** Notice meta-data, indexed by id. */
     private final Map<String, String> notices;
+    /** Directories expected to be contained within the release. */
     private final Collection<WithinDirectory> contents;
 
+    /**
+     * Constructs a description of the expected licensing qualities
+     * of a distribution.
+     * @param primaryLicense not null
+     * @param primaryOrganisationId not null
+     * @param primaryNotice possibly null
+     * @param licenses not null, possibly empty
+     * @param notices not null, possibly empty
+     * @param organisations not null, possibly empty
+     * @param contents not null, possibly empty
+     */
     public Descriptor(final License primaryLicense,
             final String primaryOrganisationId, final String primaryNotice,
             final Map<String, License> licenses,
@@ -50,44 +67,84 @@ public class Descriptor {
     }
 
     /**
+     * Gets the principle NOTICE for the main work.
      * @return the primaryNotice
      */
     public String getPrimaryNotice() {
         return this.primaryNotice;
     }
 
+    /**
+     * Collates NOTICE meta-data for resources.
+     * @return not null, possibly empty
+     */
     public Map<String, Collection<Resource>> getResourceNotices() {
         final NoticeCollator collator = new NoticeCollator();
         traverse(collator);
         return collator.resourceNotices(this.notices);
     }
 
+    /**
+     * Collates NOTICE meta-data not linked to any resource.
+     * @return not null, possibly empty
+     */
     public Set<String> getOtherNotices() {
         final NoticeCollator collator = new NoticeCollator();
         traverse(collator);
         return collator.notices(this.notices);
     }
 
+    /**
+     * Gets the license with the given id.
+     * @param id not null
+     * @return the license with the given id, or null
+     */
     public License license(final String id) {
         return this.licenses.get(id);
     }
 
+    /**
+     * Gets the principle license under which the work is licensed.
+     * @return the principle license, not null
+     */
     public License getPrimaryLicense() {
         return this.primaryLicense;
     }
 
+    /**
+     * Gets the contents expected in the distribution.
+     * @return not null, possibly null
+     */
     public Collection<WithinDirectory> getContents() {
         return this.contents;
     }
 
+    /**
+     * Is the given license the principle license for the main work?
+     * @param license not null
+     * @return true when the given license is the primary license, not null
+     */
     public boolean isPrimary(final License license) {
         return this.primaryLicense.equals(license);
     }
 
+    /**
+     * Is the given individual or group the principle organisation with responsibility
+     * for the main work.
+     * @param byOrganisation not null
+     * @return true when the given organisation is primary
+     */
     public boolean isPrimary(final ByOrganisation byOrganisation) {
         return byOrganisation.getId().equals(this.primaryOrganisationId);
     }
 
+    /**
+     * Is this directory expected to contain only material with the 
+     * primary license?
+     * @param directory not null
+     * @return true when the directory contains only material with the
+     * primary license, false otherwise
+     */
     public boolean isOnlyPrimary(final WithinDirectory directory) {
         final LicenseAndOrganisationCollator collator = new LicenseAndOrganisationCollator();
         directory.accept(collator);
@@ -95,6 +152,13 @@ public class Descriptor {
                 && collator.isOnlyOrganisation(this.primaryOrganisationId);
     }
 
+    /**
+     * Is this collection of resources licensed under the primary
+     * license by the primary organisation?
+     * @param license not null
+     * @return true when the contents are all licensed under the primary
+     * license by the primary organisation
+     */
     public boolean isOnlyPrimary(final WithLicense license) {
         final LicenseAndOrganisationCollator collator = new LicenseAndOrganisationCollator();
         license.accept(collator);
@@ -102,12 +166,21 @@ public class Descriptor {
                 && collator.isOnlyOrganisation(this.primaryOrganisationId);
     }
 
+    /**
+     * Traverses the content directories.
+     * @param visitor possibly null
+     */
     public void traverse(final Visitor visitor) {
         for (final WithinDirectory directory : getContents()) {
             directory.accept(visitor);
         }
     }
 
+    /**
+     * Traverses the given directory.
+     * @param visitor possibly null
+     * @param directoryName not null
+     */
     public void traverseDirectory(final Visitor visitor,
             final String directoryName) {
         for (final WithinDirectory directory : getContents()) {

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/License.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/License.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/License.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/License.java
Sun May 20 14:11:42 2012
@@ -24,17 +24,37 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * 
+ * Describes a software license.
  */
 public class License implements Comparable<License> {
 
+    /**
+     * Is information about source distribution required 
+     * by this license? 
+     */
     private final boolean isSourceRequired;
+    /** Template for license wording. */
     private final String baseText;
+    /** Parameters expected by the template. */
     private final Collection<String> expectedParameters;
+    /** Identifies this license. */
     private final String id;
+    /** Canonical locator for this license. */
     private final String url;
+    /** Names this license */
     private final String name;
-
+    
+    /**
+     * Constructs meta-data for a family of licenses.
+     * @param isSourceRequired true if this license requires
+     * information about source distribution to be included
+     * within the distribution
+     * @param baseText a template for the legal text, not null
+     * @param expectedParameters not null
+     * @param id not null
+     * @param url not null
+     * @param name not null
+     */
     public License(final boolean isSourceRequired, final String baseText,
             final Collection<String> expectedParameters, final String id,
             final String url, final String name) {
@@ -48,27 +68,55 @@ public class License implements Comparab
         this.name = name;
     }
 
+    /**
+     * Is source information inclusion required by this
+     * license?
+     * @return true when information about the source
+     * should be included, false otherwise
+     */
     public boolean isSourceRequired() {
         return this.isSourceRequired;
     }
 
+    /**
+     * Gets legal text expressing this license.
+     * @return not null
+     * @throws LicenseTemplateException when the text cannot
+     * be created from the template
+     */
     public String getText() throws LicenseTemplateException {
         return getText(null);
     }
 
+    /**
+     * Gets legal text expressing this license,
+     * 
+     * @param parameters possibly null
+     * @return not null
+     * @throws LicenseTemplateException when the text cannot
+     * be created from the template
+     */
     public String getText(final Map<String, String> parameters)
             throws LicenseTemplateException {
         return substituteInto(validate(parameters), this.baseText);
     }
-
+    
+    /**
+     * Gets parameters required by the template
+     * to generate a instance of this license family.
+     * @return not null, possibly empty
+     */
     public Collection<String> getExpectedParameters() {
         return this.expectedParameters;
     }
 
     /**
-     * @param parameters
-     * @return
-     * @throws LicenseTemplateException
+     * Validates that these given parameters
+     * are suitable for the template expressing the legalise.
+     * @param parameters possibly null
+     * @return parameters, not null
+     * @throws LicenseTemplateException when the parameter
+     * do not fulfill the expectations of the template
      */
     @SuppressWarnings("unchecked")
     private Map<String, String> validate(final Map<String, String> parameters)
@@ -92,9 +140,11 @@ public class License implements Comparab
     }
 
     /**
-     * @param parameters
-     * @param expectedParameters
-     * @return
+     * Do the presented parameters fulfill expectations? 
+     * @param parameters possibly null
+     * @param expectedParameters possibly null
+     * @return true when expected and presented parameters
+     * match, false otherwise
      */
     private boolean parametersMatch(final Map<String, String> parameters,
             final Collection<String> expectedParameters) {
@@ -103,14 +153,23 @@ public class License implements Comparab
                 .containsAll(keySet));
     }
 
+    /**
+     * Translates a parameter name to 
+     * the variable style used by the template
+     * @param parameterName not null
+     * @return variable in template format, not null
+     */
     private String variable(final String parameterName) {
         return "${" + parameterName + "}";
     }
 
     /**
-     * @param parameters
-     * @param trim
-     * @return
+     * Substitutes parameter values into the variable
+     * in the template legalise, parameterising 
+     * an instance of the license family.
+     * @param parameters not null
+     * @param text template text
+     * @return not null
      */
     private String substituteInto(final Map<String, String> parameters,
             final String text) {
@@ -122,7 +181,9 @@ public class License implements Comparab
     }
 
     /**
-     * @param results
+     * Stores the license by its id.
+     * @param map not null
+     * @return the license stored
      */
     public License storeIn(final Map<String, License> map) {
         map.put(getId(), this);
@@ -130,21 +191,25 @@ public class License implements Comparab
     }
 
     /**
-     * @return
+     * Gets the unique identifier for this license.
+     * @return not null
      */
     public String getId() {
         return this.id;
     }
 
     /**
-     * @return
+     * Gets a locator for this license.
+     * @return not null
      */
     public String getURL() {
         return this.url;
     }
 
     /**
-     * @return
+     * Gets a name for this license suitable for 
+     * display.
+     * @return not null
      */
     public String getName() {
         return this.name;

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseAndOrganisationCollator.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseAndOrganisationCollator.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseAndOrganisationCollator.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseAndOrganisationCollator.java
Sun May 20 14:11:42 2012
@@ -22,7 +22,7 @@ import java.util.Set;
 import java.util.TreeSet;
 
 /**
- * 
+ * Collates 
  */
 public class LicenseAndOrganisationCollator extends Visitor {
 

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseTemplateException.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseTemplateException.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseTemplateException.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/LicenseTemplateException.java
Sun May 20 14:11:42 2012
@@ -22,15 +22,19 @@ import java.util.Collection;
 import java.util.Map;
 
 /**
- * 
+ * Indicates that generating an instance of a license
+ * from the template (for the license family) has failed.
  */
 public class LicenseTemplateException extends Exception {
 
+    /** Exception are serializable, so provide a SUID. */
     private static final long serialVersionUID = -4085365930968672572L;
 
     /**
-     * @param parameters
-     * @return
+     * Builds an instance.
+     * @param parameters not null
+     * @param name not null
+     * @return not null 
      */
     public static LicenseTemplateException notLicenseTemplate(
             final Map<String, String> parameters, final String name) {
@@ -39,8 +43,10 @@ public class LicenseTemplateException ex
     }
 
     /**
-     * @param string
-     * @param parameters
+     * Constructs an instance.
+     * @param message not null
+     * @param parameters parameters passed
+     * @param name license name
      */
     public LicenseTemplateException(final String message,
             final Map<String, String> parameters, final String name) {
@@ -49,9 +55,10 @@ public class LicenseTemplateException ex
     }
 
     /**
-     * @param message
-     * @param expectedParameters
-     * @param actualParameters
+     * Constructs an instance.
+     * @param message not null
+     * @param expectedParameters not null
+     * @param actualParameters not null
      */
     public LicenseTemplateException(final String message,
             final Collection<String> expectedParameters,
@@ -61,8 +68,9 @@ public class LicenseTemplateException ex
     }
 
     /**
-     * @param string
-     * @param name
+     * Constructs an instance
+     * @param message not null
+     * @param name not null
      */
     public LicenseTemplateException(final String message, final String name) {
         // TODO improve reporting
@@ -70,9 +78,11 @@ public class LicenseTemplateException ex
     }
 
     /**
-     * @param expectedParameters
-     * @param keySet
-     * @return
+     * Builds an exception indicating that parameter passed
+     * do not fulfill expectations.
+     * @param expectedParameters not null
+     * @param actualParameters not null
+     * @return not null
      */
     public static LicenseTemplateException parameterMismatch(
             final Collection<String> expectedParameters,
@@ -82,12 +92,14 @@ public class LicenseTemplateException ex
     }
 
     /**
-     * @param name
-     * @return
+     * Builds an exception indicating that duplicate parameter
+     * names have been passed.
+     * @param name names the parameter duplicated, not null
+     * @return not null
      */
     public static LicenseTemplateException duplicateParameterName(
             final String name) {
         return new LicenseTemplateException("Duplicate parameter name.", name);
     }
 
-}
+}
\ No newline at end of file

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Organisation.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Organisation.java?rev=1340729&r1=1340728&r2=1340729&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Organisation.java
(original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Organisation.java
Sun May 20 14:11:42 2012
@@ -21,14 +21,28 @@ package org.apache.creadur.whisker.model
 import java.util.Map;
 
 /**
- * 
+ * Describes a group or individual with responsibility for 
+ * upstream distributions.
  */
 public class Organisation implements Comparable<Organisation> {
 
+    /** Identifies this group or individual with responsibility. */
     private final String id;
+    /** A name for this group or individual suitable for presentation. */
     private final String name;
+    /** A locator for the home of this group or individual. */
     private final String url;
 
+    /**
+     * Constructs an instance.
+     * @param id identifies this group or individual 
+     * with responsibility for 
+     * upstream distributions, not null
+     * @param name a name for this group or individual 
+     * suitable for presentation, not null
+     * @param url a locator for the home of this group 
+     * or individual, not null
+     */
     public Organisation(final String id, final String name, final String url) {
         super();
         this.id = id;
@@ -37,7 +51,9 @@ public class Organisation implements Com
     }
 
     /**
-     * @param organisationsById
+     * Stores this organisation by id.
+     * @param organisationsById not null
+     * @return this organisation
      */
     public Organisation storeIn(
             final Map<String, Organisation> organisationsById) {
@@ -45,16 +61,29 @@ public class Organisation implements Com
         return this;
     }
 
+    /**
+     * Gets a name for this group or individual 
+     * suitable for presentation.
+     * @return not null
+     */
     public String getName() {
         return this.name;
     }
 
+    /**
+     * Gets a locator for the home of this group 
+     * or individual.
+     * @return not null
+     */
     public String getURL() {
         return this.url;
     }
 
     /**
-     * @return
+     * Gets an identifier for this group or individual 
+     * with responsibility for 
+     * upstream distributions.
+     * @return not null
      */
     public String getId() {
         return this.id;



Mime
View raw message