NOISSUE - Create lib.rs, to allow documentation tests to be written…

… and

run:
* Add high level description of public modules in `lib.rs`
* Add docs and doc-tests for args module
* Add clippy level to enforce use of doc markdown

Signed-off-by: joshmc <[email protected]>

cargo-geiger-serde/Cargo.toml

@@ -1,9 +1,12 @@
 [package]
 authors = ["anderejd <[email protected]>"]
+categories = ["development-tools", "serialization"]
 description = "TODO: Write description"
 edition = "2018"
 license = "Apache-2.0/MIT"
+keywords = ["unsafe"]
 name = "cargo-geiger-serde"
+repository = "https://github.com/rust-secure-code/cargo-geiger"
 version = "0.1.0"
 
 [dependencies]

cargo-geiger/src/args.rs

@@ -6,6 +6,7 @@ use cargo::{CliResult, Config};
 use pico_args::Arguments;
 use std::path::PathBuf;
 
+/// Constant `&str` containing help text
 pub const HELP: &str =
     "Detects usage of unsafe Rust in a Rust crate and its dependencies.
 
@@ -85,6 +86,13 @@ pub struct Args {
 }
 
 impl Args {
+    /// Construct `Args` struct from `pico_args::Arguments` loaded from command line arguments
+    /// provided by the user
+    /// ```
+    /// # use cargo_geiger::args::Args;
+    /// let pico_arguments = pico_args::Arguments::from_env();
+    /// let args = Args::parse_args(pico_arguments);
+    /// ```
     pub fn parse_args(
         mut raw_args: Arguments,
     ) -> Result<Args, Box<dyn std::error::Error>> {
@@ -147,6 +155,17 @@ impl Args {
         Ok(args)
     }
 
+    /// Update `cargo::util::Config` with values from `Args` struct, and set the shell
+    /// colour choice
+    /// ```
+    /// # use cargo::Config;
+    /// # use cargo_geiger::args::Args;
+    /// let args = Args::parse_args(
+    ///     pico_args::Arguments::from_env()
+    /// ).unwrap();
+    /// let mut config = Config::default().unwrap();
+    /// args.update_config(&mut config);
+    /// ```
     pub fn update_config(&self, config: &mut Config) -> CliResult {
         let target_dir = None; // Doesn't add any value for cargo-geiger.
         config.configure(

cargo-geiger/src/cli.rs

@@ -1,5 +1,3 @@
-//! This module provides the bulk of the code for the `cargo-geiger` executable.
-
 // TODO: Review the module structure in this crate. There is very tight coupling
 // between the main.rs and this module. Should this module be split into smaller
 // parts? The printing and scanning can probably be further decoupled to provide
@@ -8,7 +6,7 @@
 // TODO: Investigate how cargo-clippy is implemented. Is it using syn?  Is is
 // using rustc? Is it implementing a compiler plugin?
 
-use crate::Args;
+use crate::args::Args;
 
 // TODO: Consider making this a lib.rs (again) and expose a full API, excluding
 // only the terminal output..? That API would be dependent on cargo.
@@ -53,7 +51,7 @@ pub fn get_cargo_metadata(
 
 /// TODO: Write proper documentation for this.
 /// This function seems to be looking up the active flags for conditional
-/// compilation (cargo_platform::Cfg instances).
+/// compilation (`cargo_platform::Cfg` instances).
 pub fn get_cfgs(
     config: &Config,
     target: &Option<String>,

cargo-geiger/src/lib.rs

@@ -0,0 +1,20 @@
+#![deny(clippy::cargo)]
+#![deny(clippy::doc_markdown)]
+#![forbid(unsafe_code)]
+#![forbid(warnings)]
+
+/// Argument parsing
+pub mod args;
+/// Bootstrapping functions for structs required by the CLI
+pub mod cli;
+/// Construction of the dependency graph
+pub mod graph;
+/// Mapping functionality from `cargo::core` to `cargo_metadata`
+pub mod mapping;
+/// Functions for scanning projects for unsafe code
+pub mod scan;
+
+/// Inner display formatting
+mod format;
+/// Tree construction
+mod tree;

cargo-geiger/src/main.rs

@@ -1,6 +1,8 @@
 //! The outer CLI parts of the `cargo-geiger` cargo plugin executable.
 //! TODO: Refactor this file to only deal with command line argument processing.
 
+#![deny(clippy::cargo)]
+#![deny(clippy::doc_markdown)]
 #![forbid(unsafe_code)]
 #![forbid(warnings)]
 
@@ -10,19 +12,11 @@ extern crate petgraph;
 extern crate strum;
 extern crate strum_macros;
 
-mod args;
-mod cli;
-mod format;
-mod graph;
-mod mapping;
-mod scan;
-mod tree;
-
-use crate::args::{Args, HELP};
-use crate::cli::{get_cargo_metadata, get_krates, get_workspace};
-use crate::graph::build_graph;
-use crate::mapping::{CargoMetadataParameters, QueryResolve};
-use crate::scan::scan;
+use cargo_geiger::args::{Args, HELP};
+use cargo_geiger::cli::{get_cargo_metadata, get_krates, get_workspace};
+use cargo_geiger::graph::build_graph;
+use cargo_geiger::mapping::{CargoMetadataParameters, QueryResolve};
+use cargo_geiger::scan::scan;
 
 use cargo::core::shell::Shell;
 use cargo::util::important_paths;

cargo-geiger/src/mapping.rs

@@ -9,6 +9,8 @@ use cargo_metadata::{DependencyKind, Metadata};
 use std::collections::HashSet;
 use std::path::PathBuf;
 
+/// Holds a pointer to both a `Krates` graph, and the `Metadata` struct
+/// which are often required together
 pub struct CargoMetadataParameters<'a> {
     pub krates: &'a Krates,
     pub metadata: &'a Metadata,

cargo-geiger/src/scan/default.rs

@@ -46,7 +46,7 @@ pub fn scan_unsafe(
     }
 }
 
-/// Based on code from cargo-bloat. It seems weird that CompileOptions can be
+/// Based on code from cargo-bloat. It seems weird that `CompileOptions` can be
 /// constructed without providing all standard cargo options, TODO: Open an issue
 /// in cargo?
 fn build_compile_options<'a>(

cargo-geiger/src/scan/rs_file.rs

@@ -20,7 +20,7 @@ use walkdir::{DirEntry, WalkDir};
 
 /// Provides information needed to scan for crate root
 /// `#![forbid(unsafe_code)]`.
-/// The wrapped PathBufs are canonicalized.
+/// The wrapped `PathBufs` are canonicalized.
 #[derive(Debug, PartialEq)]
 pub enum RsFile {
     /// Executable entry point source file, usually src/main.rs
@@ -247,7 +247,7 @@ fn compile_with_exec(
     Ok(())
 }
 
-/// Copy-pasted (almost) from the private module cargo::core::compiler::fingerprint.
+/// Copy-pasted (almost) from the private module `cargo::core::compiler::fingerprint`.
 ///
 /// TODO: Make a PR to the cargo project to expose this function or to expose
 /// the dependency data in some other way.

cargo-geiger/src/tree/traversal.rs

@@ -19,10 +19,10 @@ pub struct WalkDependencyParameters<'a> {
     pub visited_deps: &'a mut HashSet<cargo_metadata::PackageId>,
 }
 
-/// Printing the returned TextTreeLines in order is expected to produce a nice
+/// Printing the returned `TextTreeLines` in order is expected to produce a nice
 /// looking tree structure.
 ///
-/// TODO: Return a impl Iterator<Item = TextTreeLine ... >
+/// TODO: Return a impl `Iterator<Item = TextTreeLine ... >`
 /// TODO: Consider separating the tree vine building from the tree traversal.
 ///
 pub fn walk_dependency_tree(

geiger/Cargo.toml

@@ -1,14 +1,14 @@
 [package]
-name = "geiger"
+authors = ["anderejd <[email protected]>"]
+categories = ["development-tools", "parsing"]
 description = "Some library parts of cargo-geiger, decoupled from cargo."
-version = "0.4.5"
 edition = "2018"
-authors = ["anderejd <[email protected]>"]
-repository = "https://github.com/rust-secure-code/cargo-geiger"
-readme = "README.md"
 keywords = ["unsafe"]
-categories = ["development-tools", "parsing"]
 license = "Apache-2.0/MIT"
+name = "geiger"
+readme = "README.md"
+repository = "https://github.com/rust-secure-code/cargo-geiger"
+version = "0.4.5"
 
 [badges]
 maintenance = { status = "experimental" }