Merge pull request steveklabnik#117 from euclio/fixes

Miscellaneous fixes

Author: steveklabnik

src/cargo.rs

@@ -11,7 +11,7 @@ use error::*;
 ///
 /// ## Arguments
 ///
-/// - manifest_path: The path containing the `Cargo.toml` of the crate
+/// - `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
@@ -45,7 +45,7 @@ pub fn generate_analysis(manifest_path: &Path) -> Result<()> {
 ///
 /// ## Arguments
 ///
-/// - manifest_path: The path to the location of `Cargo.toml` of the crate being documented
+/// - `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> {
     let mut command = Command::new("cargo");
 
@@ -76,7 +76,7 @@ pub fn crate_name_from_manifest_path(manifest_path: &Path) -> Result<String> {
 ///
 /// ## Arguments
 ///
-/// - metadata: The JSON metadata of the crate.
+/// - `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,

src/json.rs

@@ -5,7 +5,7 @@ use std::collections::HashMap;
 // Sizes for the HashMaps to avoid reallocation and large HashMap sizes when we know
 // the upper limit for them
 
-/// Number of possible values in the enum item::Metadata
+/// Number of possible values in the enum `analysis::DefKind`
 pub const METADATA_SIZE: usize = 14;
 
 /// Under each item in data.relationships how many fields are there. For now we only have one which
@@ -44,48 +44,44 @@ const DATA_SIZE: usize = 1;
 ///             }
 ///         }
 ///     ]
-///}
-///```
-///
-/// ## Fields
-///
-/// - `data`: The top level crate information and documentation
-/// - `included`: The rest of the crate information and documentation
-#[derive(Serialize, Debug)]
+/// }
+/// ```
+#[derive(Debug, Default, Serialize)]
 pub struct Documentation {
+    /// The top level crate information and documentation
     data: Option<Document>,
+
+    /// The rest of the crate information and documentation
     included: Option<Vec<Document>>,
 }
 
 /// A sub type of the `Documentation` struct. It contains the majority of the data. It can be used
 /// for both the `data` and `included` field in the serialized JSON.
-///
-/// ## Fields
-///
-/// - `ty`: The type of the the item (e.g. "crate", "function", "enum", etc.)
-/// - `id`: The unique identifier associated with this item
-/// - `attributes`: The attributes associated with the item like documentation or it's name
-/// - `relationships`: An optional field used to show the relationship between the crate to the
-///   otheritems in the crate
-#[derive(Serialize, Debug)]
+#[derive(Debug, Default, Serialize)]
 pub struct Document {
     #[serde(rename = "type")]
+    /// The type of the item (e.g. "crate", "function", "enum", etc.)
     ty: String,
+
+    /// The unique identifier associated with this item
     id: String,
+
+    /// The attributes associated with the item, like documentation or its name
     attributes: HashMap<String, String>,
+
+    /// An optional field used to show the relationship between the crate to the other items in the
+    /// crate
     relationships: Option<HashMap<String, HashMap<String, Vec<Data>>>>,
 }
 
 /// Used to populate the `relationships` `data` field in the serialized JSON
-///
-/// ## Fields
-///
-/// - `ty`: The type of the the item (e.g. "crate", "function", "enum", etc.)
-/// - `id`: The unique identifier associated with this item
-#[derive(Serialize, Debug)]
+#[derive(Debug, Default, Serialize)]
 pub struct Data {
     #[serde(rename = "type")]
+    /// The type of the item (e.g. "crate", "function", "enum", etc.)
     ty: String,
+
+    /// The unique identifier associated with this item
     id: String,
 }
 

src/lib.rs

@@ -36,16 +36,15 @@ use json::*;
 pub use error::{Error, ErrorKind};
 
 /// A structure that contains various fields that hold data in order to generate doc output.
-///
-/// ## Fields
-///
-/// - `manifest_path`: Path to the directory with the `Cargo.toml` file for the crate being analyzed
-/// - `host`: Contains the Cargo analysis output for the crate being documented
-/// - `assets`: Contains all of the `Asset`s that will be output at the end (e.g. JSON, CSS, HTML
-///             and/or JS)
 pub struct Config {
+    /// Path to the directory with the `Cargo.toml` file for the crate being analyzed
     manifest_path: PathBuf,
+
+    /// Contains the Cargo analysis output for the crate being documented
     host: analysis::AnalysisHost,
+
+    /// Contains all of the `Asset`s that will be output at the end (e.g. JSON, CSS, HTML and/or
+    /// JS)
     assets: Vec<Asset>,
 }
 
@@ -55,7 +54,7 @@ impl Config {
     ///
     /// ## Arguments
     ///
-    /// - manifest_path: The path to the location of `Cargo.toml` of the crate being documented
+    /// - `manifest_path`: The path to the location of `Cargo.toml` of the crate being documented
     pub fn new(manifest_path: PathBuf, assets: Vec<Asset>) -> Result<Config> {
         let host = analysis::AnalysisHost::new(analysis::Target::Debug);
 
@@ -72,8 +71,8 @@ impl Config {
 ///
 /// ## Arguments
 ///
-/// - 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
+/// - `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)?;
 
@@ -122,8 +121,8 @@ pub fn build(config: &Config, artifacts: &[&str]) -> Result<()> {
 ///
 /// ## Arguments:
 ///
-/// - config: Contains data for what needs to be output or used. In this case the path to the
-///           `Cargo.toml` file
+/// - `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<()> {
     let manifest_path = &config.manifest_path;
 
@@ -147,11 +146,11 @@ fn generate_and_load_analysis(config: &Config) -> Result<()> {
     Ok(())
 }
 
-/// This creates the JSON documentation from the given AnalysisHost.
+/// This creates the JSON documentation from the given `AnalysisHost`.
 pub fn create_json(host: &AnalysisHost, crate_name: &str) -> Result<String> {
     let roots = host.def_roots()?;
 
-    let id = roots.iter().find(|&&(_, ref name)| name == &crate_name);
+    let id = roots.iter().find(|&&(_, ref name)| name == crate_name);
     let root_id = match id {
         Some(&(id, _)) => id,
         _ => return Err(ErrorKind::CrateErr(crate_name.to_string()).into()),
@@ -168,7 +167,7 @@ pub fn create_json(host: &AnalysisHost, crate_name: &str) -> Result<String> {
 
         let child_defs: Vec<analysis::Def> = ids.into_par_iter()
             .map(|id: analysis::Id| recur(&id, host))
-            .reduce(|| Vec::new(), |mut a: Vec<analysis::Def>,
+            .reduce(Vec::default, |mut a: Vec<analysis::Def>,
              b: Vec<analysis::Def>| {
                 a.extend(b);
                 a
@@ -209,7 +208,7 @@ pub fn create_json(host: &AnalysisHost, crate_name: &str) -> Result<String> {
         .attributes(String::from("docs"), root_def.docs);
 
     // Insert all of the different types of relationships into this `Document` type only
-    for (ty, data) in relationships.into_iter() {
+    for (ty, data) in relationships {
         data_document.relationships(ty, data);
     }
 

tests/source.rs

@@ -138,7 +138,7 @@ fn generate_analysis(source_file: &Path, tempdir: &Path) -> Result<AnalysisHost>
         Ok(())
     }
 
-    workaround(&tempdir)?;
+    workaround(tempdir)?;
 
     let host = AnalysisHost::new(Target::Debug);
     host.reload(tempdir, tempdir)?;

tests/validation.rs

@@ -33,9 +33,8 @@ mod validation_tests {
             panic!("Error: {}", err);
         });
 
-        match doc.validate() {
-            Some(errors) => panic!("Error: {:?}", errors),
-            None => (),
+        if let Some(errors) = doc.validate() {
+            panic!("Error: {:?}", errors);
         }
     }
 }