Merge pull request #111 from euclio/infer-target

Infer target to document

Author: steveklabnik

src/cargo.rs

@@ -7,27 +7,54 @@ use serde_json;
 
 use error::*;
 
-/// Invoke cargo to generate the save-analysis data for the crate being documented.
+/// The kinds of targets that we can document.
+#[derive(Debug, PartialEq, Eq)]
+pub enum TargetKind {
+    /// A `bin` target.
+    Binary,
+
+    /// A `lib` target.
+    Library,
+}
+
+/// A target of documentation.
+#[derive(Debug, PartialEq, Eq)]
+pub struct Target {
+    /// The kind of the target.
+    pub kind: TargetKind,
+
+    /// The name of the target.
+    ///
+    /// This is *not* the name of the target's crate, which is used to retrieve the analysis data.
+    /// Use the [`crate_name`] method instead.
+    ///
+    /// [`crate_name`]: ./struct.Target.html#method.crate_name
+    pub name: String,
+}
+
+impl Target {
+    /// Returns the name of the target's crate.
+    ///
+    /// This name is equivalent to the target's name, with dashes replaced by underscores.
+    pub fn crate_name(&self) -> String {
+        self.name.replace('-', "_")
+    }
+}
+
+/// Generate and parse the metadata of a cargo project.
 ///
 /// ## Arguments
 ///
 /// - `manifest_path`: The path containing the `Cargo.toml` of the crate
-pub fn generate_analysis(manifest_path: &Path) -> Result<()> {
-    // FIXME: Here we assume that we are documenting a library. This could be wrong, but it's the
-    // common case, and it ensures that we are documenting the right target in the case that the
-    // crate contains a binary and a library with the same name.
-    //
-    // Maybe we could use Cargo.toml's `doc = false` attribute to figure out the right target?
-    let mut command = Command::new("cargo");
-    command
-        .arg("check")
-        .arg("--lib")
+pub fn retrieve_metadata(manifest_path: &Path) -> Result<serde_json::Value> {
+    let output = Command::new("cargo")
+        .arg("metadata")
         .arg("--manifest-path")
         .arg(manifest_path.join("Cargo.toml"))
-        .env("RUSTFLAGS", "-Z save-analysis")
-        .env("CARGO_TARGET_DIR", manifest_path.join("target/rls"));
-
-    let output = command.output()?;
+        .arg("--no-deps")
+        .arg("--format-version")
+        .arg("1")
+        .output()?;
 
     if !output.status.success() {
         return Err(
@@ -38,24 +65,33 @@ pub fn generate_analysis(manifest_path: &Path) -> Result<()> {
         );
     }
 
-    Ok(())
+    Ok(serde_json::from_slice(&output.stdout)?)
 }
 
-/// Grab the name of the binary or library from it's `Cargo.toml` file.
+/// Invoke cargo to generate the save-analysis data for the crate being documented.
 ///
 /// ## Arguments
 ///
-/// - `manifest_path`: The path to the location of `Cargo.toml` of the crate being documented
-pub fn crate_name_from_manifest_path(manifest_path: &Path) -> Result<String> {
+/// - `manifest_path`: The path containing the `Cargo.toml` of the crate
+/// - `target`: The target that we should generate the analysis data for
+pub fn generate_analysis(manifest_path: &Path, target: &Target) -> Result<()> {
     let mut command = Command::new("cargo");
 
     command
-        .arg("metadata")
+        .arg("check")
         .arg("--manifest-path")
         .arg(manifest_path.join("Cargo.toml"))
-        .arg("--no-deps")
-        .arg("--format-version")
-        .arg("1");
+        .env("RUSTFLAGS", "-Z save-analysis")
+        .env("CARGO_TARGET_DIR", manifest_path.join("target/rls"));
+
+    match target.kind {
+        TargetKind::Library => {
+            command.arg("--lib");
+        }
+        TargetKind::Binary => {
+            command.args(&["--bin", &target.name]);
+        }
+    }
 
     let output = command.output()?;
 
@@ -68,83 +104,181 @@ pub fn crate_name_from_manifest_path(manifest_path: &Path) -> Result<String> {
         );
     }
 
-    let metadata = serde_json::from_slice(&output.stdout)?;
-    crate_name_from_metadata(&metadata)
+    Ok(())
 }
 
-/// Parse the crate name of the binary or library from crate metadata.
+/// Parse the library target from the crate metadata.
 ///
 /// ## Arguments
 ///
-/// - `metadata`: The JSON metadata of the crate.
-fn crate_name_from_metadata(metadata: &serde_json::Value) -> Result<String> {
-    let targets = match metadata["packages"][0]["targets"].as_array() {
-        Some(targets) => targets,
-        None => return Err(ErrorKind::Json("targets is not an array").into()),
-    };
-
-    for target in targets {
-        let crate_types = match target["crate_types"].as_array() {
-            Some(crate_types) => crate_types,
-            None => return Err(ErrorKind::Json("crate types is not an array").into()),
-        };
-
-        for crate_type in crate_types {
-            let ty = match crate_type.as_str() {
-                Some(t) => t,
-                None => {
-                    return Err(
-                        ErrorKind::Json("crate type contents are not a string").into(),
-                    )
-                }
-            };
+/// - metadata: The JSON metadata of the crate.
+pub fn target_from_metadata(metadata: &serde_json::Value) -> Result<Target> {
+    // We can expect at least one package and target, otherwise the metadata generation would have
+    // failed.
+    let targets = metadata["packages"][0]["targets"].as_array().expect(
+        "`targets` is not an array",
+    );
+
+    let mut targets = targets
+        .into_iter()
+        .flat_map(|target| {
+            let name = target["name"].as_str().expect("`name` is not a string");
+            let kinds = target["kind"].as_array().expect("`kind` is not an array");
 
-            if ty == "lib" {
-                match target["name"].as_str() {
-                    Some(name) => return Ok(name.replace('-', "_")),
-                    None => return Err(ErrorKind::Json("target name is not a string").into()),
-                }
+            if kinds.len() != 1 {
+                return Some(Err(
+                    ErrorKind::Json(
+                        format!("expected one kind for target '{}'", name),
+                    ).into(),
+                ));
             }
+
+            let kind = match kinds[0].as_str().unwrap() {
+                "lib" => TargetKind::Library,
+                "bin" => TargetKind::Binary,
+                _ => return None,
+            };
+
+            let target = Target {
+                name: name.to_owned(),
+                kind,
+            };
+
+            Some(Ok(target))
+        })
+        .collect::<Result<Vec<_>>>()?;
+
+    if targets.is_empty() {
+        bail!(ErrorKind::Json(
+            "no targets with supported kinds (`bin`, `lib`) found"
+                .into(),
+        ));
+    } else if targets.len() == 1 {
+        Ok(targets.remove(0))
+    } else {
+        // FIXME(#105): Handle more than one target.
+        print!("warning: Found more than one target to document. ");
+        let (mut libs, mut bins): (Vec<_>, Vec<_>) =
+            targets.into_iter().partition(|target| match target.kind {
+                TargetKind::Library => true,
+                TargetKind::Binary => false,
+            });
+
+        if !libs.is_empty() {
+            println!("Documenting the library.");
+            Ok(libs.remove(0))
+        } else {
+            let target = bins.remove(0);
+            println!("Documenting the first binary: {}", target.name);
+            Ok(target)
         }
     }
-
-    Err(
-        ErrorKind::Json("cargo metadata contained no targets").into(),
-    )
 }
 
 #[cfg(test)]
 mod tests {
+    use super::{Target, TargetKind};
+
     #[test]
-    fn crate_name_from_metadata() {
+    fn target_from_metadata() {
         let metadata = json!({
             "packages": [
                 {
                     "name": "underscored_name",
                     "targets": [
                         {
-                            "crate_types": [ "lib" ],
+                            "kind": [ "lib" ],
                             "name": "underscored_name",
                         },
                     ],
                 },
             ],
         });
-        assert_eq!(&super::crate_name_from_metadata(&metadata).unwrap(), "underscored_name");
+        let target = super::target_from_metadata(&metadata).unwrap();
+        assert_eq!(target, Target { kind: TargetKind::Library, name: "underscored_name".into() });
+        assert_eq!(&target.crate_name(), "underscored_name");
 
         let metadata = json!({
             "packages": [
                 {
                     "name": "dashed-name",
                     "targets": [
                         {
-                            "crate_types": [ "lib" ],
+                            "kind": [ "lib" ],
                             "name": "dashed-name",
                         },
                     ],
                 },
             ],
         });
-        assert_eq!(&super::crate_name_from_metadata(&metadata).unwrap(), "dashed_name");
+        let target = super::target_from_metadata(&metadata).unwrap();
+        assert_eq!(target, Target { kind: TargetKind::Library, name: "dashed-name".into() });
+        assert_eq!(&target.crate_name(), "dashed_name");
+
+        let metadata = json!({
+            "packages": [
+                {
+                    "name": "underscored_name",
+                    "targets": [
+                        {
+                            "kind": [ "bin" ],
+                            "name": "underscored_name",
+                        },
+                    ],
+                },
+            ],
+        });
+        let target = super::target_from_metadata(&metadata).unwrap();
+        assert_eq!(target, Target { kind: TargetKind::Binary, name: "underscored_name".into() });
+        assert_eq!(&target.crate_name(), "underscored_name");
+
+        let metadata = json!({
+            "packages": [
+                {
+                    "name": "library",
+                    "targets": [
+                        {
+                            "kind": [ "lib" ],
+                            "name": "library",
+                        },
+                    ],
+                },
+            ],
+        });
+        assert_eq!(super::target_from_metadata(&metadata).unwrap().kind, TargetKind::Library);
+
+        let metadata = json!({
+            "packages": [
+                {
+                    "name": "binary",
+                    "targets": [
+                        {
+                            "kind": [ "bin" ],
+                            "name": "binary",
+                        },
+                    ],
+                },
+            ],
+        });
+        assert_eq!(super::target_from_metadata(&metadata).unwrap().kind, TargetKind::Binary);
+
+        let metadata = json!({
+            "packages": [
+                {
+                    "name": "library",
+                    "targets": [
+                        {
+                            "kind": [ "lib" ],
+                            "name": "library",
+                        },
+                        {
+                            "kind": [ "test" ],
+                            "name": "other_kind",
+                        },
+                    ],
+                },
+            ],
+        });
+        assert_eq!(super::target_from_metadata(&metadata).unwrap().kind, TargetKind::Library);
     }
 }

src/error.rs

@@ -16,7 +16,7 @@ error_chain! {
 
         /// Thrown whenever the `JSON` grabbed from somewhere else is not what is expected.
         /// This is usually thrown when grabbing data output from `Cargo`
-        Json(location: &'static str) {
+        Json(location: String) {
             description("Unexpected JSON response")
             display("Unexpected JSON response from {}", location)
         }

src/lib.rs

@@ -30,6 +30,7 @@ use indicatif::ProgressBar;
 use rayon::prelude::*;
 
 use assets::Asset;
+use cargo::Target;
 use error::*;
 use json::*;
 
@@ -74,9 +75,9 @@ impl Config {
 /// - `config`: The `Config` struct that contains the data needed to generate the documentation
 /// - `artifacts`: A slice containing what assets should be output at the end
 pub fn build(config: &Config, artifacts: &[&str]) -> Result<()> {
-    generate_and_load_analysis(config)?;
-
-    let crate_name = cargo::crate_name_from_manifest_path(&config.manifest_path)?;
+    let metadata = cargo::retrieve_metadata(&config.manifest_path)?;
+    let target = cargo::target_from_metadata(&metadata)?;
+    generate_and_load_analysis(config, &target)?;
 
     let output_path = config.manifest_path.join("target/doc");
     fs::create_dir_all(&output_path)?;
@@ -86,7 +87,7 @@ pub fn build(config: &Config, artifacts: &[&str]) -> Result<()> {
         spinner.enable_steady_tick(50);
         spinner.set_message("Generating JSON: In Progress");
 
-        let json = create_json(&config.host, &crate_name)?;
+        let json = create_json(&config.host, &target.crate_name())?;
 
         let mut json_path = output_path.clone();
         json_path.push("data.json");
@@ -123,14 +124,15 @@ pub fn build(config: &Config, artifacts: &[&str]) -> Result<()> {
 ///
 /// - `config`: Contains data for what needs to be output or used. In this case the path to the
 ///             `Cargo.toml` file
-fn generate_and_load_analysis(config: &Config) -> Result<()> {
+/// - `target`: The target to document
+fn generate_and_load_analysis(config: &Config, target: &Target) -> Result<()> {
     let manifest_path = &config.manifest_path;
 
     let spinner = ProgressBar::new_spinner();
     spinner.enable_steady_tick(50);
     spinner.set_message("Generating save analysis data: In Progress");
 
-    if let Err(e) = cargo::generate_analysis(manifest_path) {
+    if let Err(e) = cargo::generate_analysis(manifest_path, target) {
         spinner.finish_with_message("Generating save analysis data: Error");
         return Err(e);
     }