Auto merge of #4559 - derekdreery:add_docs, r=alexcrichton

Add some more docs

Add some more docs for various parts of cargo, and add/improve a few debug implementations.

src/cargo/core/package.rs

@@ -20,12 +20,13 @@ use util::errors::{CargoResult, CargoResultExt};
 // TODO: Is manifest_path a relic?
 #[derive(Clone, Debug)]
 pub struct Package {
-    // The package's manifest
+    /// The package's manifest
     manifest: Manifest,
-    // The root of the package
+    /// The root of the package
     manifest_path: PathBuf,
 }
 
+/// A Package in a form where `Serialize` can be derived.
 #[derive(Serialize)]
 struct SerializedPackage<'a> {
     name: &'a str,
@@ -69,6 +70,7 @@ impl ser::Serialize for Package {
 }
 
 impl Package {
+    /// Create a package from a manifest and its location
     pub fn new(manifest: Manifest,
                manifest_path: &Path) -> Package {
         Package {
@@ -77,25 +79,38 @@ impl Package {
         }
     }
 
+    /// Calculate the Package from the manifest path (and cargo configuration).
     pub fn for_path(manifest_path: &Path, config: &Config) -> CargoResult<Package> {
         let path = manifest_path.parent().unwrap();
         let source_id = SourceId::for_path(path)?;
         let (pkg, _) = ops::read_package(manifest_path, &source_id, config)?;
         Ok(pkg)
     }
 
+    /// Get the manifest dependencies
     pub fn dependencies(&self) -> &[Dependency] { self.manifest.dependencies() }
+    /// Get the manifest
     pub fn manifest(&self) -> &Manifest { &self.manifest }
+    /// Get the path to the manifest
     pub fn manifest_path(&self) -> &Path { &self.manifest_path }
+    /// Get the name of the package
     pub fn name(&self) -> &str { self.package_id().name() }
+    /// Get the PackageId object for the package (fully defines a packge)
     pub fn package_id(&self) -> &PackageId { self.manifest.package_id() }
+    /// Get the root folder of the package
     pub fn root(&self) -> &Path { self.manifest_path.parent().unwrap() }
+    /// Get the summary for the package
     pub fn summary(&self) -> &Summary { self.manifest.summary() }
+    /// Get the targets specified in the manifest
     pub fn targets(&self) -> &[Target] { self.manifest.targets() }
+    /// Get the current package version
     pub fn version(&self) -> &Version { self.package_id().version() }
+    /// Get the package authors
     pub fn authors(&self) -> &Vec<String> { &self.manifest.metadata().authors }
+    /// Whether the package is set to publish
     pub fn publish(&self) -> bool { self.manifest.publish() }
 
+    /// Whether the package uses a custom build script for any target
     pub fn has_custom_build(&self) -> bool {
         self.targets().iter().any(|t| t.is_custom_build())
     }

src/cargo/core/shell.rs

@@ -7,37 +7,60 @@ use termcolor::{self, StandardStream, Color, ColorSpec, WriteColor};
 
 use util::errors::CargoResult;
 
-#[derive(Clone, Copy, PartialEq)]
+/// The requested verbosity of output
+#[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Verbosity {
     Verbose,
     Normal,
     Quiet
 }
 
+/// An abstraction around a `Write`able object that remembers preferences for output verbosity and
+/// color.
 pub struct Shell {
+    /// the `Write`able object, either with or without color support (represented by different enum
+    /// variants)
     err: ShellOut,
+    /// How verbose messages should be
     verbosity: Verbosity,
 }
 
 impl fmt::Debug for Shell {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "Shell")
+        match &self.err {
+            &ShellOut::Write(_) => f.debug_struct("Shell")
+                .field("verbosity", &self.verbosity)
+                .finish(),
+            &ShellOut::Stream(_, color_choice) => f.debug_struct("Shell")
+                .field("verbosity", &self.verbosity)
+                .field("color_choice", &color_choice)
+                .finish()
+        }
     }
 }
 
+/// A `Write`able object, either with or without color support
 enum ShellOut {
+    /// A plain write object without color support
     Write(Box<Write>),
+    /// Color-enabled stdio, with information on whether color should be used
     Stream(StandardStream, ColorChoice),
 }
 
-#[derive(PartialEq, Clone, Copy)]
+/// Whether messages should use color output
+#[derive(Debug, PartialEq, Clone, Copy)]
 pub enum ColorChoice {
+    /// Force color output
     Always,
+    /// Force disable color output
     Never,
+    /// Intelligently guess whether to use color output
     CargoAuto,
 }
 
 impl Shell {
+    /// Create a new shell (color choice and verbosity), defaulting to 'auto' color and verbose
+    /// output.
     pub fn new() -> Shell {
         Shell {
             err: ShellOut::Stream(
@@ -48,13 +71,16 @@ impl Shell {
         }
     }
 
+    /// Create a shell from a plain writable object, with no color, and max verbosity.
     pub fn from_write(out: Box<Write>) -> Shell {
         Shell {
             err: ShellOut::Write(out),
             verbosity: Verbosity::Verbose,
         }
     }
 
+    /// Print a message, where the status will have `color` color, and can be justified. The
+    /// messages follows without color.
     fn print(&mut self,
              status: &fmt::Display,
              message: &fmt::Display,
@@ -68,16 +94,19 @@ impl Shell {
         }
     }
 
+    /// Get a reference to the underlying writer
     pub fn err(&mut self) -> &mut Write {
         self.err.as_write()
     }
 
+    /// Shortcut to right-align and color green a status message.
     pub fn status<T, U>(&mut self, status: T, message: U) -> CargoResult<()>
         where T: fmt::Display, U: fmt::Display
     {
         self.print(&status, &message, Green, true)
     }
 
+    /// Shortcut to right-align a status message.
     pub fn status_with_color<T, U>(&mut self,
                                    status: T,
                                    message: U,
@@ -87,6 +116,7 @@ impl Shell {
         self.print(&status, &message, color, true)
     }
 
+    /// Run the callback only if we are in verbose mode
     pub fn verbose<F>(&mut self, mut callback: F) -> CargoResult<()>
         where F: FnMut(&mut Shell) -> CargoResult<()>
     {
@@ -96,6 +126,7 @@ impl Shell {
         }
     }
 
+    /// Run the callback if we are not in verbose mode.
     pub fn concise<F>(&mut self, mut callback: F) -> CargoResult<()>
         where F: FnMut(&mut Shell) -> CargoResult<()>
     {
@@ -105,25 +136,30 @@ impl Shell {
         }
     }
 
+    /// Print a red 'error' message
     pub fn error<T: fmt::Display>(&mut self, message: T) -> CargoResult<()> {
         self.print(&"error:", &message, Red, false)
     }
 
+    /// Print an amber 'warning' message
     pub fn warn<T: fmt::Display>(&mut self, message: T) -> CargoResult<()> {
         match self.verbosity {
             Verbosity::Quiet => Ok(()),
             _ => self.print(&"warning:", &message, Yellow, false),
         }
     }
 
+    /// Update the verbosity of the shell
     pub fn set_verbosity(&mut self, verbosity: Verbosity) {
         self.verbosity = verbosity;
     }
 
+    /// Get the verbosity of the shell
     pub fn verbosity(&self) -> Verbosity {
         self.verbosity
     }
 
+    /// Update the color choice (always, never, or auto) from a string.
     pub fn set_color_choice(&mut self, color: Option<&str>) -> CargoResult<()> {
         if let ShellOut::Stream(ref mut err, ref mut cc) =  self.err {
             let cfg = match color {
@@ -142,6 +178,10 @@ impl Shell {
         Ok(())
     }
 
+    /// Get the current color choice
+    ///
+    /// If we are not using a color stream, this will always return Never, even if the color choice
+    /// has been set to something else.
     pub fn color_choice(&self) -> ColorChoice {
         match self.err {
             ShellOut::Stream(_, cc) => cc,
@@ -151,6 +191,8 @@ impl Shell {
 }
 
 impl ShellOut {
+    /// Print out a message with a status. The status comes first and is bold + the given color.
+    /// The status can be justified, in which case the max width that will right align is 12 chars.
     fn print(&mut self,
              status: &fmt::Display,
              message: &fmt::Display,
@@ -182,6 +224,7 @@ impl ShellOut {
         Ok(())
     }
 
+    /// Get this object as a `io::Write`.
     fn as_write(&mut self) -> &mut Write {
         match *self {
             ShellOut::Stream(ref mut err, _) => err,
@@ -191,6 +234,7 @@ impl ShellOut {
 }
 
 impl ColorChoice {
+    /// Convert our color choice to termcolor's version
     fn to_termcolor_color_choice(&self) -> termcolor::ColorChoice {
         match *self {
             ColorChoice::Always => termcolor::ColorChoice::Always,