update javadoc (thanks to Stephen Nesbitt) IVY-129

git-svn-id: https://svn.apache.org/repos/asf/incubator/ivy/trunk@484093 13f79535-47bb-0310-9956-ffa450edef68

src/java/fr/jayasoft/ivy/repository/Repository.java

@@ -10,23 +10,114 @@ import java.io.File;
 import java.io.IOException;
 import java.util.List;
 
+/**
+ * Represents a collection of resources available to Ivy. Ivy uses one or more
+ * repositories as both a source of resources for Ivy enabled build systems and
+ * as a distribution center for resources generated by Ivy enabled build systems.
+ * </p>
+ * <p>A repository supports the following fundamental operations
+ * <ul>
+ *   <li>retrieving a resource from the repository.</li>
+ *   <li>transfering a resource to the repository.</li>
+ *   <li>retrieving a listing of resources.</li>
+ * </ul>
+ * </p>
+ * <h4>Resource Retrieval</h4>
+ * </p>
+ * <p>{@link #get} retrieves a resource specified by a provided identifier creating a new file .</p>
+ * </p>
+ * <h4>resource Publication</h4>
+ * </p>
+ * <p>{@link #put} transfers a file to the repository.
+ * </p>
+ * </p>
+ * <h4>resource Listing</h4>
+ * </p>
+ * <p>{@link #list} returns a listing of file like objects
+ *    belonging to a specified parent directory.</p>
+ * </p>
+ */
 public interface Repository {
+	
+	/**
+	 * Return the resource associated with a specified identifier.
+	 * 
+	 * @param source A string identifying the resource.
+	 * @return The resource associated with the resource identifier.
+	 * @throws IOException On failure to get resource.
+	 */
     Resource getResource(String source)  throws IOException;
-    void get(String source, File destination) throws IOException;
-    void put(File source, String destination, boolean overwrite) throws IOException;
+    
     /**
-     * Returns the list of all resources names that can be found in the given
-     * parent.
-     * @param parent
-     * @return a List of String, the names of the resources that can be found in the given
-     * parent
+     * Fetch a resource from the repository.
+     * 
+     * @param source A string identifying the resource to be fetched.
+     * @param destination Where to place the fetched resource.
+     * @throws IOException On retrieval failure.
+     */
+    void get(String source, File destination) throws IOException;
+    
+    
+    /**
+     * Transfer a resource to the repository
+     * 
+     * @param source The local file to be transferred.
+     * @param destination Where to transfer the resource.
+     * @param overwrite Whether the transfer should overwrite an existing resource.
+     * @throws IOException On publication failure.
+     */
+    void put(File source, String destination, boolean overwrite) throws IOException;
+    
+    /**
+     * Return a listing of resources
+     * 
+     * @param parent The parent directory from which to generate the listing.
+     * @return A listing of the parent directory's file content.
+     * @throws IOException On listing failure.
      */
     List list(String parent) throws IOException;
     
+    /**
+     * Add a listener to the repository.
+     * 
+     * @param listener The listener to attach to the repository.
+     */
     void addTransferListener(TransferListener listener);
+    
+    /**
+     * Remove a listener on the repository
+     * 
+     * @param listener The listener to remove
+     */
     void removeTransferListener(TransferListener listener);
+    
+    /**
+     * Determine if a given listener is attached to the repository.
+     * 
+     * @param listener The listener being quireied
+     * @return <code>true</code> if the provided listener is attached to the repository,
+     *         <code>false</code> if not.
+     */
     boolean hasTransferListener(TransferListener listener);
+    
+    /**
+     * Get the repository's file separator string.
+     * 
+     * @return The repository's file separator delimiter
+     */
     String getFileSeparator();
+    
+    /**
+     * Normalize a string.
+     * 
+     * @param source The string to normalize.
+     * @return The normalized string.
+     */
     String standardize(String source);
+    
+    /**
+     * Return the name of the repository
+     * 
+     */
     String getName();
 }