From 0d6984aa88f41976979c7a52a73a3a466d621faa Mon Sep 17 00:00:00 2001
From: Mark Harrah <dmharrah@gmail.com>
Date: Sun, 10 Apr 2011 21:30:03 -0400
Subject: [PATCH] some API documentation for UpdateReport

---
 ivy/UpdateReport.scala | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/ivy/UpdateReport.scala b/ivy/UpdateReport.scala
index 50097eeeb..999103e86 100644
--- a/ivy/UpdateReport.scala
+++ b/ivy/UpdateReport.scala
@@ -5,21 +5,51 @@ package sbt
 
 	import java.io.File
 
+/** Provides information about dependency resolution.
+* It does not include information about evicted modules, only about the modules ultimately selected by the conflict manager.
+* This means that for a given configuration, there should only be one revision for a given organization and module name.
+* @param configurations a sequence containing one report for each configuration resolved.
+* @see sbt.RichUpdateReport
+ */
 final class UpdateReport(val configurations: Seq[ConfigurationReport])
 {
 	override def toString = "Update report:\n" + configurations.mkString
+
+	/** All resolved modules in all configurations. */
 	def allModules: Seq[ModuleID] = configurations.flatMap(_.allModules).distinct
+
 	def retrieve(f: (String, ModuleID, Artifact, File) => File): UpdateReport =
 		new UpdateReport(configurations map { _ retrieve f} )
+
+	/** Gets the report for the given configuration, or `None` if the configuration was not resolved.*/
 	def configuration(s: String) = configurations.find(_.configuration == s)
+
+	/** Gets the names of all resolved configurations.  This `UpdateReport` contains one `ConfigurationReport` for each configuration in this list. */
+	def configurations: Seq[String] = configurations.map(_.configuration)
 }
+
+/** Provides information about resolution of a single configuration.
+* @param configuration the configuration this report is for.
+* @param modules a seqeuence containing one report for each module resolved for this configuration.
+*/
 final class ConfigurationReport(val configuration: String, val modules: Seq[ModuleReport])
 {
 	override def toString = "\t" + configuration + ":\n" + modules.mkString
+
+	/** All resolved modules for this configuration.
+	* For a given organization and module name, there is only one revision/`ModuleID` in this sequence.
+	*/
 	def allModules: Seq[ModuleID] = modules.map(_.module)
+
 	def retrieve(f: (String, ModuleID, Artifact, File) => File): ConfigurationReport =
 		new ConfigurationReport(configuration, modules map { _.retrieve( (mid,art,file) => f(configuration, mid, art, file)) })
 }
+
+/** Provides information about the resolution of a module.
+* This information is in the context of a specific configuration.
+* @param module the `ModuleID` this report is for.
+* @param artifacts the resolved artifacts for this module, paired with the File the artifact was retrieved to.  This File may be in the
+*/
 final class ModuleReport(val module: ModuleID, val artifacts: Seq[(Artifact, File)], val missingArtifacts: Seq[Artifact])
 {
 	override def toString =
@@ -34,12 +64,18 @@ final class ModuleReport(val module: ModuleID, val artifacts: Seq[(Artifact, Fil
 object UpdateReport
 {
 	implicit def richUpdateReport(report: UpdateReport): RichUpdateReport = new RichUpdateReport(report)
+
+	/** Provides extra methods for filtering the contents of an `UpdateReport` and for obtaining references to a selected subset of the underlying files. */
 	final class RichUpdateReport(report: UpdateReport)
 	{
 			import DependencyFilter._
-
+		/** Obtains all successfully retrieved files in all configurations and modules. */
 		def allFiles: Seq[File] = matching(DependencyFilter.allPass)
+
+		/** Obtains all successfully retrieved files in configurations, modules, and artifacts matching the specified filter. */
 		def matching(f: DependencyFilter): Seq[File] = select0(f).distinct
+
+		/** Obtains all successfully retrieved files matching all provided filters.  An unspecified argument matches all files. */
 		def select(configuration: ConfigurationFilter = configurationFilter(), module: ModuleFilter = moduleFilter(), artifact: ArtifactFilter = artifactFilter()): Seq[File] =
 			matching(DependencyFilter.make(configuration, module, artifact))
 
@@ -49,6 +85,7 @@ object UpdateReport
 				file
 			}
 			
+		/** Constructs a new report that only contains files matching the specified filter.*/
 		def filter(f: DependencyFilter): UpdateReport =
 		{
 			val newConfigurations = report.configurations.map { confReport =>