svn commit: r1340793 - /creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java

[rd...@apache.org]

Author: rdonkin
Date: Sun May 20 18:28:52 2012
New Revision: 1340793

URL: http://svn.apache.org/viewvc?rev=1340793&view=rev
Log:
More documentation

Modified:
    creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java

Modified: creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java?rev=1340793&r1=1340792&r2=1340793&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java (original)
+++ creadur/whisker/trunk/apache-whisker-model/src/main/java/org/apache/creadur/whisker/model/Resource.java Sun May 20 18:28:52 2012
@@ -14,21 +14,32 @@
  * "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;
 
 /**
- * 
+ * A resource expected in a software distribution.
  */
 public class Resource implements Comparable<Resource> {
 
+    /** Names this resource. */
     private final String name;
+    /** Optional link to a notice for this resource. */
     private final String noticeId;
+    /** 
+     * Optional describes how source may be obtained 
+     * for this resource.
+     */
     private final String source;
 
     /**
-     * @param name
+     * Constructs a resource in a software distribution.
+     * @param name not null
+     * @param noticeId identifies the notice for this resource,
+     * null when there is no NOTICE
+     * @param source describes how source may be obtained,
+     * null when this is not needed
      */
     public Resource(final String name, final String noticeId,
             final String source) {
@@ -39,21 +50,27 @@ public class Resource implements Compara
     }
 
     /**
-     * @return the name
+     * Gets the name for this resource
+     * expected in a software distribution.
+     * @return not null
      */
     public String getName() {
         return this.name;
     }
 
     /**
-     * @return the noticeId
+     * Gets an identifier for the optional NOTICE.
+     * @return an identifier for the NOTICE,
+     * or null when the resource has no NOTICE
      */
     public String getNoticeId() {
         return this.noticeId;
     }
 
     /**
+     * Based on name.
      * @see java.lang.Object#hashCode()
+     * @return hash code for the name
      */
     @Override
     public int hashCode() {
@@ -65,7 +82,10 @@ public class Resource implements Compara
     }
 
     /**
+     * Based on name.
      * @see java.lang.Object#equals(java.lang.Object)
+     * @param obj possibly null
+     * @return equality based on name
      */
     @Override
     public boolean equals(final Object obj) {
@@ -90,7 +110,9 @@ public class Resource implements Compara
     }
 
     /**
+     * Gets a description suitable for logging.
      * @see java.lang.Object#toString()
+     * @return a description suitable for logging
      */
     @Override
     public String toString() {
@@ -98,14 +120,18 @@ public class Resource implements Compara
     }
 
     /**
+     * Based on name.
      * @see java.lang.Comparable#compareTo(java.lang.Object)
+     * @param other
+     * @return comparison based on name
      */
     public int compareTo(final Resource other) {
         return getName().compareTo(other.getName());
     }
 
     /**
-     * @param visitor
+     * Accepts a visitor.
+     * @param visitor possibly null
      */
     public void accept(final Visitor visitor) {
         if (visitor != null && visitor.traverseResource()) {
@@ -114,14 +140,17 @@ public class Resource implements Compara
     }
 
     /**
-     * @return the source
+     * Gets a locator for the source.
+     * @return a source locator, possibly null
      */
     public String getSource() {
         return this.source;
     }
 
     /**
-     * @return
+     * Is this resource linked to source?
+     * @return true when this resource has linked source,
+     * false otherwise
      */
     public boolean hasSource() {
         return getSource() != null && !"".equals(getSource());