some javadocs for the new metadata-only call in the repository system

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@761488 13f79535-47bb-0310-9956-ffa450edef68

maven-repository/src/main/java/org/apache/maven/repository/MetadataGraph.java

@@ -23,7 +23,7 @@ import java.util.ArrayList;
 import java.util.Collection;
 
 /**
- *
+ * This is the main graph data structure used by the RepositorySystem to present tree and graph objects. 
  *
  * @author Oleg Gusakov
  * @version $Id$
@@ -31,7 +31,10 @@ import java.util.Collection;
  */
 public class MetadataGraph
 {
+    /** all graph nodes */
     Collection<MetadataGraphNode> nodes;
+
+    /** entry point for tree-like structures */
     MetadataGraphNode             entry;
     
     public MetadataGraph( MetadataGraphNode entry )
@@ -51,6 +54,12 @@ public class MetadataGraph
         nodes.add( node );
     }
 
+    /**
+     * find a node by the GAV (metadata)
+     * 
+     * @param md
+     * @return
+     */
     public MetadataGraphNode findNode( MavenArtifactMetadata md )
     {
         for( MetadataGraphNode mgn : nodes )
@@ -63,11 +72,21 @@ public class MetadataGraph
         return node;
     }
     
+    /**
+     * getter
+     * 
+     * @return
+     */
     public MetadataGraphNode getEntry()
     {
         return entry;
     }
     
+    /**
+     * getter
+     * 
+     * @return
+     */
     public Collection<MetadataGraphNode> getNodes()
     {
         return nodes;

maven-repository/src/main/java/org/apache/maven/repository/MetadataGraphNode.java

@@ -23,7 +23,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- *
+ * MetadataGraph node - as it's a directed graph - holds adjacency lists for incident and exident nodes
  *
  * @author Oleg Gusakov
  * @version $Id$
@@ -31,9 +31,13 @@ import java.util.List;
  */
 public class MetadataGraphNode
 {
+    /** node payload */
     MavenArtifactMetadata   metadata;
 
+    /** nodes, incident to this (depend on me) */
     List<MetadataGraphNode> inNodes;
+    
+    /** nodes, exident to this (I depend on) */
     List<MetadataGraphNode> exNodes;
     
     public MetadataGraphNode()

maven-repository/src/main/java/org/apache/maven/repository/RepositorySystem.java

@@ -66,6 +66,15 @@ public interface RepositorySystem
 
     ArtifactResolutionResult resolve( ArtifactResolutionRequest request );
 
+    /**
+     * this is the new metadata-based entry point into repository system. By default - it will transitively resolve metadata
+     * for the supplied root GAV and return a flat set of dependency metadatas. Tweaking the request allows user to ask for 
+     * various formats of the response - resolved tree, resolved graph or dirty tree. Only the resolved tree is implemented now
+     * in MercuryRepositorySystem, LegacyRepositorySystem ignores this call for now.  
+     * 
+     * @param request - supplies all necessary details for the resolution configuration
+     * @return
+     */
     MetadataResolutionResult resolveMetadata( MetadataResolutionRequest request );
        
     //REMOVE