Some moer docs

diff --git a/Cargo.lock b/Cargo.lock
index 2feeeafad8556aeb13f6212f5afdba12bdec2f12..e6435473f4d51180644527d5a6c9bb5fa2d135a3 100644 (file)
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,13 +2,13 @@
 name = "cargo"
 version = "0.23.0"
 dependencies = [
- "advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "atty 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "atty 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
  "bufstream 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)",
  "cargotest 0.1.0",
  "core-foundation 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)",
  "crates-io 0.12.0",
  "crossbeam 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "crypto-hash 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "curl 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)",
  "docopt 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "env_logger 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -29,8 +29,7 @@ dependencies = [
  "libgit2-sys 0.6.15 (registry+https://github.com/rust-lang/crates.io-index)",
  "log 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)",
  "miow 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
- "num_cpus 1.6.2 (registry+https://github.com/rust-lang/crates.io-index)",
- "openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)",
+ "num_cpus 1.7.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "psapi-sys 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "same-file 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)",
  "scoped-tls 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -75,11 +74,12 @@ dependencies = [
 
 [[package]]
 name = "atty"
-version = "0.2.2"
+version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "kernel32-sys 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
  "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)",
+ "termion 1.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "winapi 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
@@ -155,6 +155,22 @@ dependencies = [
  "cc 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "commoncrypto"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "commoncrypto-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "commoncrypto-sys"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "conv"
 version = "0.3.3"
@@ -202,6 +218,18 @@ name = "crossbeam"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 
+[[package]]
+name = "crypto-hash"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "commoncrypto 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "hex 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)",
+ "winapi 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "curl"
 version = "0.4.8"
@@ -248,7 +276,7 @@ name = "docopt"
 version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
- "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)",
  "regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde 1.0.15 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde_derive 1.0.15 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -399,7 +427,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "crossbeam 0.2.10 (registry+https://github.com/rust-lang/crates.io-index)",
  "globset 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)",
  "log 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)",
  "memchr 1.0.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -432,7 +460,7 @@ dependencies = [
 
 [[package]]
 name = "lazy_static"
-version = "0.2.8"
+version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 
 [[package]]
@@ -621,7 +649,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 
 [[package]]
 name = "num_cpus"
-version = "1.6.2"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -634,7 +662,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "bitflags 0.9.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "foreign-types 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)",
  "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)",
  "openssl-sys 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -693,6 +721,14 @@ name = "redox_syscall"
 version = "0.1.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 
+[[package]]
+name = "redox_termios"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "regex"
 version = "0.1.80"
@@ -878,6 +914,16 @@ dependencies = [
  "wincolor 0.1.4 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "termion"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)",
+ "redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)",
+ "redox_termios 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "thread-id"
 version = "2.0.0"
@@ -900,7 +946,7 @@ name = "thread_local"
 version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
- "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)",
  "unreachable 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
@@ -1019,7 +1065,7 @@ dependencies = [
 "checksum advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "e06588080cb19d0acb6739808aafa5f26bfb2ca015b2b6370028b44cf7cb8a9a"
 "checksum aho-corasick 0.5.3 (registry+https://github.com/rust-lang/crates.io-index)" = "ca972c2ea5f742bfce5687b9aef75506a764f61d37f8f649047846a9686ddb66"
 "checksum aho-corasick 0.6.3 (registry+https://github.com/rust-lang/crates.io-index)" = "500909c4f87a9e52355b26626d890833e9e1d53ac566db76c36faa984b889699"
-"checksum atty 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "d912da0db7fa85514874458ca3651fe2cddace8d0b0505571dbdcd41ab490159"
+"checksum atty 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "21e50800ec991574876040fff8ee46b136a53e985286fbe6a3bdfe6421b78860"
 "checksum backtrace 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "99f2ce94e22b8e664d95c57fff45b98a966c2252b60691d0b7aeeccd88d70983"
 "checksum backtrace-sys 0.1.14 (registry+https://github.com/rust-lang/crates.io-index)" = "c63ea141ef8fdb10409d0f5daf30ac51f84ef43bff66f16627773d2a292cd189"
 "checksum bitflags 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "aad18937a628ec6abcd26d1489012cc0e18c21798210f491af69ded9b881106d"
@@ -1028,11 +1074,14 @@ dependencies = [
 "checksum cc 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "7db2f146208d7e0fbee761b09cd65a7f51ccc38705d4e7262dad4d73b12a76b1"
 "checksum cfg-if 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "d4c819a1287eb618df47cc647173c5c4c66ba19d888a6e50d605672aed3140de"
 "checksum cmake 0.1.26 (registry+https://github.com/rust-lang/crates.io-index)" = "357c07e7a1fc95732793c1edb5901e1a1f305cfcf63a90eb12dbd22bdb6b789d"
+"checksum commoncrypto 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "d056a8586ba25a1e4d61cb090900e495952c7886786fc55f909ab2f819b69007"
+"checksum commoncrypto-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "1fed34f46747aa73dfaa578069fd8279d2818ade2b55f38f22a9401c7f4083e2"
 "checksum conv 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "78ff10625fd0ac447827aa30ea8b861fead473bb60aeb73af6c1c58caf0d1299"
 "checksum core-foundation 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "5909502e547762013619f4c4e01cc7393c20fe2d52d7fa471c1210adb2320dc7"
 "checksum core-foundation-sys 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "bc9fb3d6cb663e6fd7cf1c63f9b144ee2b1e4a78595a0451dd34bff85b9a3387"
 "checksum crossbeam 0.2.10 (registry+https://github.com/rust-lang/crates.io-index)" = "0c5ea215664ca264da8a9d9c3be80d2eaf30923c259d03e870388eb927508f97"
 "checksum crossbeam 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "8837ab96533202c5b610ed44bc7f4183e7957c1c8f56e8cc78bb098593c8ba0a"
+"checksum crypto-hash 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "34903878eec1694faf53cae8473a088df333181de421d4d3d48061d6559fe602"
 "checksum curl 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)" = "7034c534a1d7d22f7971d6088aa9d281d219ef724026c3428092500f41ae9c2c"
 "checksum curl-sys 0.3.15 (registry+https://github.com/rust-lang/crates.io-index)" = "4bee31aa3a079d5f3ff9579ea4dcfb1b1a17a40886f5f467436d383e78134b55"
 "checksum custom_derive 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)" = "ef8ae57c4978a2acd8b869ce6b9ca1dfe817bff704c220209fdef2c0b75a01b9"
@@ -1058,7 +1107,7 @@ dependencies = [
 "checksum itoa 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)" = "8324a32baf01e2ae060e9de58ed0bc2320c9a2833491ee36cd3b4c414de4db8c"
 "checksum jobserver 0.1.6 (registry+https://github.com/rust-lang/crates.io-index)" = "443ae8bc0af6c106e6e8b77e04684faecc1a5ce94e058f4c2b0a037b0ea1b133"
 "checksum kernel32-sys 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "7507624b29483431c0ba2d82aece8ca6cdba9382bff4ddd0f7490560c056098d"
-"checksum lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)" = "3b37545ab726dd833ec6420aaba8231c5b320814b9029ad585555d2a03e94fbf"
+"checksum lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)" = "c9e5e58fa1a4c3b915a561a78a22ee0cac6ab97dca2504428bc1cb074375f8d5"
 "checksum libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)" = "d1419b2939a0bc44b77feb34661583c7546b532b192feab36249ab584b86856c"
 "checksum libgit2-sys 0.6.15 (registry+https://github.com/rust-lang/crates.io-index)" = "205fc37e829c5b36de63d14c8dc8b62c5a6a2519b16318ed0977079ca97256a9"
 "checksum libssh2-sys 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)" = "0db4ec23611747ef772db1c4d650f8bd762f07b461727ec998f953c614024b75"
@@ -1079,7 +1128,7 @@ dependencies = [
 "checksum num-iter 0.1.34 (registry+https://github.com/rust-lang/crates.io-index)" = "7485fcc84f85b4ecd0ea527b14189281cf27d60e583ae65ebc9c088b13dffe01"
 "checksum num-rational 0.1.39 (registry+https://github.com/rust-lang/crates.io-index)" = "288629c76fac4b33556f4b7ab57ba21ae202da65ba8b77466e6d598e31990790"
 "checksum num-traits 0.1.40 (registry+https://github.com/rust-lang/crates.io-index)" = "99843c856d68d8b4313b03a17e33c4bb42ae8f6610ea81b28abe076ac721b9b0"
-"checksum num_cpus 1.6.2 (registry+https://github.com/rust-lang/crates.io-index)" = "aec53c34f2d0247c5ca5d32cca1478762f301740468ee9ee6dcb7a0dd7a0c584"
+"checksum num_cpus 1.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "514f0d73e64be53ff320680ca671b64fe3fb91da01e1ae2ddc99eb51d453b20d"
 "checksum openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)" = "816914b22eb15671d62c73442a51978f311e911d6a6f6cbdafa6abce1b5038fc"
 "checksum openssl-probe 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "d98df0270d404ccd3c050a41d579c52d1db15375168bb3471e04ec0f5f378daf"
 "checksum openssl-sys 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)" = "1e4c63a7d559c1e5afa6d6a9e6fa34bbc5f800ffc9ae08b72c605420b0c4f5e8"
@@ -1089,6 +1138,7 @@ dependencies = [
 "checksum quote 0.3.15 (registry+https://github.com/rust-lang/crates.io-index)" = "7a6e920b65c65f10b2ae65c831a81a073a89edd28c7cce89475bff467ab4167a"
 "checksum rand 0.3.16 (registry+https://github.com/rust-lang/crates.io-index)" = "eb250fd207a4729c976794d03db689c9be1d634ab5a1c9da9492a13d8fecbcdf"
 "checksum redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)" = "8dde11f18c108289bef24469638a04dce49da56084f2d50618b226e47eb04509"
+"checksum redox_termios 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "7e891cfe48e9100a70a3b6eb652fef28920c117d366339687bd5576160db0f76"
 "checksum regex 0.1.80 (registry+https://github.com/rust-lang/crates.io-index)" = "4fd4ace6a8cf7860714a2c2280d6c1f7e6a413486c13298bbc86fd3da019402f"
 "checksum regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "1731164734096285ec2a5ec7fea5248ae2f5485b3feeb0115af4fda2183b2d1b"
 "checksum regex-syntax 0.3.9 (registry+https://github.com/rust-lang/crates.io-index)" = "f9ec002c35e86791825ed294b50008eea9ddfc8def4420124fbc6b08db834957"
@@ -1113,6 +1163,7 @@ dependencies = [
 "checksum tar 0.4.13 (registry+https://github.com/rust-lang/crates.io-index)" = "281285b717926caa919ad905ef89c63d75805c7d89437fb873100925a53f2b1b"
 "checksum tempdir 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)" = "87974a6f5c1dfb344d733055601650059a3363de2a6104819293baff662132d6"
 "checksum termcolor 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "9065bced9c3e43453aa3d56f1e98590b8455b341d2fa191a1090c0dd0b242c75"
+"checksum termion 1.5.1 (registry+https://github.com/rust-lang/crates.io-index)" = "689a3bdfaab439fd92bc87df5c4c78417d3cbe537487274e9b0b2dce76e92096"
 "checksum thread-id 2.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "a9539db560102d1cef46b8b78ce737ff0bb64e7e18d35b2a5688f7d097d0ff03"
 "checksum thread_local 0.2.7 (registry+https://github.com/rust-lang/crates.io-index)" = "8576dbbfcaef9641452d5cf0df9b0e7eeab7694956dd33bb61515fb8f18cfdd5"
 "checksum thread_local 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)" = "1697c4b57aeeb7a536b647165a2825faddffb1d3bad386d507709bd51a90bb14"

diff --git a/src/cargo/core/package.rs b/src/cargo/core/package.rs
index afc047f88f6e3538894ae0d53719493b8a627e9a..90e7c811f01701c86ac1effbdb487aabfa519df1 100644 (file)
--- a/src/cargo/core/package.rs
+++ b/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,6 +79,7 @@ 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)?;
@@ -84,18 +87,30 @@ impl Package {
         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())
     }

diff --git a/src/cargo/core/source.rs b/src/cargo/core/source.rs
index b9218bd5acabb6645f47765ee46f4fb7464a65f8..01d659919087c0e759d4bfc740545a2c399f0ae3 100644 (file)
--- a/src/cargo/core/source.rs
+++ b/src/cargo/core/source.rs
@@ -21,6 +21,7 @@ use util::{Config, CargoResult, ToUrl};
 /// A Source finds and downloads remote packages based on names and
 /// versions.
 pub trait Source: Registry {
+    /// Returns the `SourceId` corresponding to this source
     fn source_id(&self) -> &SourceId;
 
     /// The update method performs any network operations required to
@@ -56,27 +57,34 @@ pub trait Source: Registry {
 }
 
 impl<'a, T: Source + ?Sized + 'a> Source for Box<T> {
+    /// Forwards to `Source::source_id`
     fn source_id(&self) -> &SourceId {
         (**self).source_id()
     }
 
+    /// Forwards to `Source::update`
     fn update(&mut self) -> CargoResult<()> {
         (**self).update()
     }
 
+    /// Forwards to `Source::download`
     fn download(&mut self, id: &PackageId) -> CargoResult<Package> {
         (**self).download(id)
     }
 
+    /// Forwards to `Source::fingerprint`
     fn fingerprint(&self, pkg: &Package) -> CargoResult<String> {
         (**self).fingerprint(pkg)
     }
 
+    /// Forwards to `Source::verify`
     fn verify(&self, pkg: &PackageId) -> CargoResult<()> {
         (**self).verify(pkg)
     }
 }
 
+/// The possible kinds of code source. Along with a URL, this fully defines the
+/// source
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 enum Kind {
     /// Kind::Git(<git reference>) represents a git repository
@@ -91,10 +99,14 @@ enum Kind {
     Directory,
 }
 
+/// Information to find a specific commit in a git repository
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum GitReference {
+    /// from a tag
     Tag(String),
+    /// from the HEAD of a branch
     Branch(String),
+    /// from a specific revision
     Rev(String),
 }
 
@@ -104,16 +116,23 @@ pub struct SourceId {
     inner: Arc<SourceIdInner>,
 }
 
+/// Unique identifier for a source of packages.
 #[derive(Eq, Clone, Debug)]
 struct SourceIdInner {
+    /// The source URL
     url: Url,
+    /// `git::canonicalize_url(url)` for the url field
     canonical_url: Url,
+    /// The source kind
     kind: Kind,
     // e.g. the exact git revision of the specified branch for a Git Source
     precise: Option<String>,
 }
 
 impl SourceId {
+    /// Create a SourceId object from the kind and url.
+    ///
+    /// The canonical url will be calculated, but the precise field will not
     fn new(kind: Kind, url: Url) -> CargoResult<SourceId> {
         let source_id = SourceId {
             inner: Arc::new(SourceIdInner {
@@ -174,29 +193,36 @@ impl SourceId {
         }
     }
 
+    /// A view of the `SourceId` that can be `Display`ed as a URL
     pub fn to_url(&self) -> SourceIdToUrl {
         SourceIdToUrl { inner: &*self.inner }
     }
 
-    // Pass absolute path
+    /// Create a SourceId from a filesystem path.
+    ///
+    /// Pass absolute path
     pub fn for_path(path: &Path) -> CargoResult<SourceId> {
         let url = path.to_url()?;
         SourceId::new(Kind::Path, url)
     }
 
+    /// Crate a SourceId from a git reference
     pub fn for_git(url: &Url, reference: GitReference) -> CargoResult<SourceId> {
         SourceId::new(Kind::Git(reference), url.clone())
     }
 
+    /// Create a SourceId from a registry url
     pub fn for_registry(url: &Url) -> CargoResult<SourceId> {
         SourceId::new(Kind::Registry, url.clone())
     }
 
+    /// Create a SourceId from a local registry path
     pub fn for_local_registry(path: &Path) -> CargoResult<SourceId> {
         let url = path.to_url()?;
         SourceId::new(Kind::LocalRegistry, url)
     }
 
+    /// Create a SourceId from a directory path
     pub fn for_directory(path: &Path) -> CargoResult<SourceId> {
         let url = path.to_url()?;
         SourceId::new(Kind::Directory, url)
@@ -212,9 +238,9 @@ impl SourceId {
             static WARNED: AtomicBool = ATOMIC_BOOL_INIT;
             if !WARNED.swap(true, SeqCst) {
                 config.shell().warn("custom registry support via \
-                                          the `registry.index` configuration is \
-                                          being removed, this functionality \
-                                          will not work in the future")?;
+                                     the `registry.index` configuration is \
+                                     being removed, this functionality \
+                                     will not work in the future")?;
             }
             &index[..]
         } else {
@@ -224,16 +250,22 @@ impl SourceId {
         SourceId::for_registry(&url)
     }
 
+    /// Get this source URL
     pub fn url(&self) -> &Url {
         &self.inner.url
     }
+
+    /// Is this source from a filesystem path
     pub fn is_path(&self) -> bool {
         self.inner.kind == Kind::Path
     }
+
+    /// Is this source from a registry (either local or not)
     pub fn is_registry(&self) -> bool {
         self.inner.kind == Kind::Registry || self.inner.kind == Kind::LocalRegistry
     }
 
+    /// Is this source from a git repository
     pub fn is_git(&self) -> bool {
         match self.inner.kind {
             Kind::Git(_) => true,
@@ -271,10 +303,12 @@ impl SourceId {
         }
     }
 
+    /// Get the value of the precise field
     pub fn precise(&self) -> Option<&str> {
         self.inner.precise.as_ref().map(|s| &s[..])
     }
 
+    /// Get the git reference if this is a git source, otherwise None.
     pub fn git_reference(&self) -> Option<&GitReference> {
         match self.inner.kind {
             Kind::Git(ref s) => Some(s),
@@ -282,6 +316,7 @@ impl SourceId {
         }
     }
 
+    /// Create a new SourceId from this source with the given `precise`
     pub fn with_precise(&self, v: Option<String>) -> SourceId {
         SourceId {
             inner: Arc::new(SourceIdInner {
@@ -291,6 +326,7 @@ impl SourceId {
         }
     }
 
+    /// Whether the remote registry is the standard https://crates.io
     pub fn is_default_registry(&self) -> bool {
         match self.inner.kind {
             Kind::Registry => {}
@@ -299,6 +335,10 @@ impl SourceId {
         self.inner.url.to_string() == CRATES_IO
     }
 
+    /// Hash `self`
+    ///
+    /// For paths, remove the workspace prefix so the same source will give the
+    /// same hash in different locations.
     pub fn stable_hash<S: hash::Hasher>(&self, workspace: &Path, into: &mut S) {
         if self.is_path() {
             if let Ok(p) = self.inner.url.to_file_path().unwrap().strip_prefix(workspace) {
@@ -383,6 +423,9 @@ impl fmt::Display for SourceId {
 // This custom implementation handles situations such as when two git sources
 // point at *almost* the same URL, but not quite, even when they actually point
 // to the same repository.
+/// This method tests for self and other values to be equal, and is used by ==.
+///
+/// For git repositories, the canonical url is checked.
 impl PartialEq for SourceIdInner {
     fn eq(&self, other: &SourceIdInner) -> bool {
         if self.kind != other.kind {
@@ -441,6 +484,7 @@ impl Hash for SourceId {
     }
 }
 
+/// A `Display`able view into a SourceId that will write it as a url
 pub struct SourceIdToUrl<'a> {
     inner: &'a SourceIdInner,
 }
@@ -477,6 +521,8 @@ impl<'a> fmt::Display for SourceIdToUrl<'a> {
 }
 
 impl GitReference {
+    /// Returns a `Display`able view of this git reference, or None if using
+    /// the head of the "master" branch
     pub fn pretty_ref(&self) -> Option<PrettyRef> {
         match *self {
             GitReference::Branch(ref s) if *s == "master" => None,
@@ -485,6 +531,7 @@ impl GitReference {
     }
 }
 
+/// A git reference that can be `Display`ed
 pub struct PrettyRef<'a> {
     inner: &'a GitReference,
 }
@@ -499,26 +546,32 @@ impl<'a> fmt::Display for PrettyRef<'a> {
     }
 }
 
+/// A `HashMap` of `SourceId` -> `Box<Source>`
 #[derive(Default)]
 pub struct SourceMap<'src> {
     map: HashMap<SourceId, Box<Source + 'src>>,
 }
 
+/// A `std::collection::hash_map::Values` for `SourceMap`
 pub type Sources<'a, 'src> = Values<'a, SourceId, Box<Source + 'src>>;
 
+/// A `std::collection::hash_map::IterMut` for `SourceMap`
 pub struct SourcesMut<'a, 'src: 'a> {
     inner: IterMut<'a, SourceId, Box<Source + 'src>>,
 }
 
 impl<'src> SourceMap<'src> {
+    /// Create an empty map
     pub fn new() -> SourceMap<'src> {
         SourceMap { map: HashMap::new() }
     }
 
+    /// Like `HashMap::contains_key`
     pub fn contains(&self, id: &SourceId) -> bool {
         self.map.contains_key(id)
     }
 
+    /// Like `HashMap::get`
     pub fn get(&self, id: &SourceId) -> Option<&(Source + 'src)> {
         let source = self.map.get(id);
 
@@ -528,6 +581,7 @@ impl<'src> SourceMap<'src> {
         })
     }
 
+    /// Like `HashMap::get_mut`
     pub fn get_mut(&mut self, id: &SourceId) -> Option<&mut (Source + 'src)> {
         self.map.get_mut(id).map(|s| {
             let s: &mut (Source + 'src) = &mut **s;
@@ -535,27 +589,34 @@ impl<'src> SourceMap<'src> {
         })
     }
 
+    /// Like `HashMap::get`, but first calculates the `SourceId` from a
+    /// `PackageId`
     pub fn get_by_package_id(&self, pkg_id: &PackageId) -> Option<&(Source + 'src)> {
         self.get(pkg_id.source_id())
     }
 
+    /// Like `HashMap::insert`, but derives the SourceId key from the Source
     pub fn insert(&mut self, source: Box<Source + 'src>) {
         let id = source.source_id().clone();
         self.map.insert(id, source);
     }
 
+    /// Like `HashMap::is_empty`
     pub fn is_empty(&self) -> bool {
         self.map.is_empty()
     }
 
+    /// Like `HashMap::len`
     pub fn len(&self) -> usize {
         self.map.len()
     }
 
+    /// Like `HashMap::values`
     pub fn sources<'a>(&'a self) -> Sources<'a, 'src> {
         self.map.values()
     }
 
+    /// Like `HashMap::iter_mut`
     pub fn sources_mut<'a>(&'a mut self) -> SourcesMut<'a, 'src> {
         SourcesMut { inner: self.map.iter_mut() }
     }

diff --git a/src/cargo/ops/cargo_rustc/context.rs b/src/cargo/ops/cargo_rustc/context.rs
index 192badff27871670a6a271d60e434ed6f9ac4f25..7e85c0d5802e6ad23c13fecfd6475f4fc5895305 100755 (executable)
--- a/src/cargo/ops/cargo_rustc/context.rs
+++ b/src/cargo/ops/cargo_rustc/context.rs
@@ -64,8 +64,11 @@ pub struct Unit<'a> {
 pub struct Context<'a, 'cfg: 'a> {
     /// The workspace the build is for
     pub ws: &'a Workspace<'cfg>,
+    /// The cargo configuration
     pub config: &'cfg Config,
+    /// The dependency graph for our build
     pub resolve: &'a Resolve,
+    /// Information on the compilation output
     pub compilation: Compilation<'cfg>,
     pub packages: &'a PackageSet<'cfg>,
     pub build_state: Arc<BuildState>,

diff --git a/src/cargo/util/to_url.rs b/src/cargo/util/to_url.rs
index 5508bb9aadfac2afa330c4aeccef9764264b5131..f6a4d23a5ec4db3e2bbee7628950f2bb8bd3b4b1 100644 (file)
--- a/src/cargo/util/to_url.rs
+++ b/src/cargo/util/to_url.rs
@@ -4,7 +4,9 @@ use url::Url;
 
 use util::CargoResult;
 
+/// A type that can be converted to a Url
 pub trait ToUrl {
+    /// Performs the conversion
     fn to_url(self) -> CargoResult<Url>;
 }