nix_rs: Enforce API docs (in CI)

- Use `#![warn(missing_docs)]` to enforce that all public entites are documented
- Make an exception for `schema.rs` & `output.rs` since those can be documented as part of #235

Author: srid

crates/nix_rs/src/command.rs

@@ -72,12 +72,12 @@ static NIXCMD: OnceCell<NixCmd> = OnceCell::const_new();
 ///
 /// The command will be highlighted to distinguish it (for copying) from the
 /// rest of the instrumentation parameters.
-
 #[instrument(name = "command")]
 pub fn trace_cmd(cmd: &tokio::process::Command) {
     trace_cmd_with("🐚", cmd);
 }
 
+/// Like [traace_cmd] but with a custom icon
 #[instrument(name = "command")]
 pub fn trace_cmd_with(icon: &str, cmd: &tokio::process::Command) {
     use colored::Colorize;
@@ -227,19 +227,24 @@ fn to_cli(cmd: &tokio::process::Command) -> String {
 /// Errors when running and interpreting the output of a nix command
 #[derive(Error, Debug)]
 pub enum NixCmdError {
+    /// A [CommandError]
     #[error("Command error: {0}")]
     CmdError(#[from] CommandError),
 
+    /// Failed to unicode-decode the output of a command
     #[error("Failed to decode command stdout (utf8 error): {0}")]
     DecodeErrorUtf8(#[from] std::string::FromUtf8Error),
 
+    /// Failed to parse the output of a command
     #[error("Failed to decode command stdout (from_str error): {0}")]
     DecodeErrorFromStr(#[from] FromStrError),
 
+    /// Failed to parse the output of a command as JSON
     #[error("Failed to decode command stdout (json error): {0}")]
     DecodeErrorJson(#[from] serde_json::Error),
 }
 
+/// Errors when parsing a string into a type
 #[derive(Debug)]
 pub struct FromStrError(String);
 
@@ -251,10 +256,14 @@ impl Display for FromStrError {
 
 impl std::error::Error for FromStrError {}
 
+/// Errors when running a command
 #[derive(Error, Debug)]
 pub enum CommandError {
+    /// Error when spawning a child process
     #[error("Child process error: {0}")]
     ChildProcessError(#[from] std::io::Error),
+
+    /// Child process exited unsuccessfully
     #[error(
         "Process exited unsuccessfully. exit_code={:?}{}",
         exit_code,
@@ -264,9 +273,13 @@ pub enum CommandError {
         },
     )]
     ProcessFailed {
+        /// The stderr of the process, if available.
         stderr: Option<String>,
+        /// The exit code of the process
         exit_code: Option<i32>,
     },
+
+    /// Failed to decode the stderr of a command
     #[error("Failed to decode command stderr: {0}")]
     Decode(#[from] std::string::FromUtf8Error),
 }

crates/nix_rs/src/config.rs

@@ -19,13 +19,21 @@ use super::flake::system::System;
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub struct NixConfig {
+    /// Number of CPU cores used for nix builds
     pub cores: ConfigVal<i32>,
+    /// Experimental features currently enabled
     pub experimental_features: ConfigVal<Vec<String>>,
+    /// Extra platforms to build for
     pub extra_platforms: ConfigVal<Vec<String>>,
+    /// The flake registry to use to lookup atomic flake inputs
     pub flake_registry: ConfigVal<String>,
+    /// Maximum number of jobs to run in parallel
     pub max_jobs: ConfigVal<i32>,
+    /// Cache substituters
     pub substituters: ConfigVal<Vec<Url>>,
+    /// Current system
     pub system: ConfigVal<System>,
+    /// Trusted users
     pub trusted_users: ConfigVal<Vec<TrustedUserValue>>,
 }
 
@@ -91,15 +99,19 @@ impl NixConfig {
     }
 }
 
+/// Error type for `NixConfig`
 #[derive(thiserror::Error, Debug)]
 pub enum NixConfigError {
+    /// A [NixCmdError]
     #[error("Nix command error: {0}")]
     NixCmdError(#[from] NixCmdError),
 
+    /// A [NixCmdError] with a static lifetime
     #[error("Nix command error: {0}")]
     NixCmdErrorStatic(#[from] &'static NixCmdError),
 }
 
+/// Accepted value for "trusted-users" in nix.conf
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, DeserializeFromStr)]
 pub enum TrustedUserValue {
     /// All users are trusted
@@ -123,6 +135,7 @@ impl TrustedUserValue {
         }
     }
 
+    /// Display the nix.conf original string
     pub fn display_original(val: &[TrustedUserValue]) -> String {
         val.iter()
             .map(|x| match x {

crates/nix_rs/src/copy.rs

@@ -1,3 +1,4 @@
+//! Rust module for `nix copy`.
 use crate::{
     command::{CommandError, NixCmd},
     store::uri::StoreURI,

crates/nix_rs/src/detsys_installer.rs

@@ -14,6 +14,7 @@ pub struct DetSysNixInstaller {
 }
 
 impl DetSysNixInstaller {
+    /// Detects if the DetSys nix-installer is installed
     pub fn detect() -> Result<Option<Self>, BadInstallerVersion> {
         let nix_installer_path = Path::new("/nix/nix-installer");
         if nix_installer_path.exists() {
@@ -46,14 +47,22 @@ impl Display for InstallerVersion {
     }
 }
 
+/// Errors that can occur when trying to get the [DetSysNixInstaller] version
 #[derive(Error, Debug)]
 pub enum BadInstallerVersion {
+    /// Regex error
     #[error("Regex error: {0}")]
     Regex(#[from] regex::Error),
+
+    /// Failed to decode installer output
     #[error("Failed to decode installer output: {0}")]
     Decode(#[from] std::string::FromUtf8Error),
+
+    /// Failed to parse installer version
     #[error("Failed to parse installer version: {0}")]
     Parse(#[from] std::num::ParseIntError),
+
+    /// Failed to fetch installer version
     #[error("Failed to fetch installer version: {0}")]
     Command(std::io::Error),
 }

crates/nix_rs/src/env.rs

@@ -95,6 +95,7 @@ pub enum OS {
     MacOS {
         /// Using nix-darwin
         nix_darwin: bool,
+        /// Architecture
         arch: MacOSArch,
     },
     /// On NixOS
@@ -103,19 +104,26 @@ pub enum OS {
     Other(os_info::Type),
 }
 
+/// macOS CPU architecture
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum MacOSArch {
+    /// Apple Silicon
     Arm64(AppleEmulation),
+    /// Other architecture
     Other(Option<String>),
 }
 
+/// Apple emulation mode
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum AppleEmulation {
+    /// Not running on Apple Silicon
     None,
+    /// Running under Rosetta
     Rosetta,
 }
 
 impl AppleEmulation {
+    /// Detect Apple emulation mode for current process
     pub fn new() -> Self {
         use is_proc_translated::is_proc_translated;
         if is_proc_translated() {
@@ -133,6 +141,7 @@ impl Default for AppleEmulation {
 }
 
 impl MacOSArch {
+    /// Create a [MacOSArch] from an OS architecture string
     pub fn from(os_arch: Option<&str>) -> MacOSArch {
         match os_arch {
             Some("arm64") => MacOSArch::Arm64(AppleEmulation::new()),
@@ -162,6 +171,7 @@ impl Display for OS {
 }
 
 impl OS {
+    /// Detect the OS
     pub async fn detect() -> Self {
         let os_info = tokio::task::spawn_blocking(os_info::get).await.unwrap();
         let os_type = os_info.os_type();
@@ -221,6 +231,7 @@ impl Display for NixInstaller {
 }
 
 impl NixInstaller {
+    /// Detect the Nix installer
     pub fn detect() -> Result<Self, NixEnvError> {
         match super::detsys_installer::DetSysNixInstaller::detect()? {
             Some(installer) => Ok(NixInstaller::DetSys(installer)),
@@ -230,18 +241,17 @@ impl NixInstaller {
 }
 
 /// Errors while trying to fetch [NixEnv]
-
 #[derive(thiserror::Error, Debug)]
 pub enum NixEnvError {
-    #[error("Cannot find $USER: {0}")]
-    UserError(#[from] std::env::VarError),
-
+    /// Unable to find user groups
     #[error("Failed to fetch groups: {0}")]
     GroupsError(std::io::Error),
 
+    /// Unable to find /nix volume
     #[error("Unable to find root disk or /nix volume")]
     NoDisk,
 
+    /// Unable to find Nix installer
     #[error("Failed to detect Nix installer: {0}")]
     InstallerError(#[from] super::detsys_installer::BadInstallerVersion),
 }

crates/nix_rs/src/flake/command.rs

@@ -1,3 +1,4 @@
+//! Nix commands for working with flakes
 use std::{
     collections::{BTreeMap, HashMap},
     path::PathBuf,

crates/nix_rs/src/flake/eval.rs

@@ -1,3 +1,4 @@
+//! Work with `nix eval`
 use crate::command::{CommandError, NixCmd, NixCmdError};
 
 use super::{command::FlakeOptions, url::FlakeUrl};

crates/nix_rs/src/flake/metadata.rs

@@ -1,3 +1,4 @@
+//! Work with `nix flake metadata`
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 

crates/nix_rs/src/flake/outputs.rs

@@ -1,4 +1,6 @@
 //! Nix flake outputs
+// TODO: Document this module!
+#![allow(missing_docs)]
 
 use lazy_static::lazy_static;
 use serde::{Deserialize, Serialize};

crates/nix_rs/src/flake/schema.rs

@@ -1,6 +1,7 @@
 //! High-level schema of a flake
 //!
 //! TODO: Consolidate with `outputs.rs`
+#![allow(missing_docs)]
 use std::collections::BTreeMap;
 
 use serde::{Deserialize, Serialize};

crates/nix_rs/src/flake/system.rs

@@ -16,15 +16,20 @@ use serde_with::{DeserializeFromStr, SerializeDisplay};
     Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, SerializeDisplay, DeserializeFromStr,
 )]
 pub enum System {
+    /// macOS system
     Darwin(Arch),
+    /// Linux system
     Linux(Arch),
+    /// Other system
     Other(String),
 }
 
 /// CPU architecture in the system
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum Arch {
+    /// aarch64
     Aarch64,
+    /// x86_64
     X86_64,
 }
 

crates/nix_rs/src/flake/url/attr.rs

@@ -1,3 +1,4 @@
+//! Work with flake attributes
 use serde::{Deserialize, Serialize};
 
 /// The (optional) attribute output part of a [super::FlakeUrl]
@@ -7,10 +8,12 @@ use serde::{Deserialize, Serialize};
 pub struct FlakeAttr(pub Option<String>);
 
 impl FlakeAttr {
+    /// Create a new [FlakeAttr]
     pub fn new(attr: &str) -> Self {
         FlakeAttr(Some(attr.to_owned()))
     }
 
+    /// A missing flake attribute
     pub fn none() -> Self {
         FlakeAttr(None)
     }

crates/nix_rs/src/flake/url/mod.rs

@@ -1,3 +1,4 @@
+//! Work with flake URLs
 pub mod attr;
 mod core;
 pub mod qualified_attr;

crates/nix_rs/src/flake/url/qualified_attr.rs

@@ -1,3 +1,4 @@
+//! Flake attributes that are "qualified"
 use crate::{
     command::{NixCmd, NixCmdError},
     flake::eval::nix_eval_attr,
@@ -35,11 +36,14 @@ where
     }
 }
 
+/// Error type for [nix_eval_qualified_attr]
 #[derive(thiserror::Error, Debug)]
 pub enum QualifiedAttrError {
+    /// When the attribute is not found in the flake
     #[error("Unexpected attribute, when config not present in flake: {0}")]
     UnexpectedAttribute(String),
 
+    /// A [NixCmdError]
     #[error("Nix command error: {0}")]
     CommandError(#[from] NixCmdError),
 }

crates/nix_rs/src/info.rs

@@ -9,7 +9,9 @@ use crate::{config::NixConfig, env::NixEnv, version::NixVersion};
 pub struct NixInfo {
     /// Nix version string
     pub nix_version: NixVersion,
+    /// nix.conf configuration
     pub nix_config: NixConfig,
+    /// Environment in which Nix was installed
     pub nix_env: NixEnv,
 }
 
@@ -42,17 +44,22 @@ impl NixInfo {
     }
 }
 
+/// Error type for [NixInfo]
 #[derive(thiserror::Error, Debug)]
 pub enum NixInfoError {
+    /// A [NixCmdError]
     #[error("Nix command error: {0}")]
     NixCmdError(#[from] crate::command::NixCmdError),
 
+    /// A [NixCmdError] with a static lifetime
     #[error("Nix command error: {0}")]
     NixCmdErrorStatic(#[from] &'static crate::command::NixCmdError),
 
+    /// A [NixEnvError]
     #[error("Nix environment error: {0}")]
     NixEnvError(#[from] crate::env::NixEnvError),
 
+    /// A [NixConfigError]
     #[error("Nix config error: {0}")]
     NixConfigError(#[from] &'static crate::config::NixConfigError),
 }

crates/nix_rs/src/lib.rs

@@ -2,6 +2,7 @@
 //!
 //! This crate exposes various types representing what nix command gives us,
 //! along with a `from_nix` command to evaluate them.
+#![warn(missing_docs)]
 pub mod command;
 pub mod config;
 pub mod copy;

crates/nix_rs/src/store/command.rs

@@ -1,4 +1,4 @@
-/// Rust wrapper for `nix-store`
+//! Rust wrapper for `nix-store`
 use std::path::PathBuf;
 
 use crate::command::{CommandError, NixCmdError};
@@ -14,6 +14,7 @@ use super::path::StorePath;
 pub struct NixStoreCmd;
 
 impl NixStoreCmd {
+    /// Get the associated [Command]
     pub fn command(&self) -> Command {
         let mut cmd = Command::new("nix-store");
         cmd.kill_on_drop(true);
@@ -101,9 +102,11 @@ impl NixStoreCmd {
 /// `nix-store` command errors
 #[derive(Error, Debug)]
 pub enum NixStoreCmdError {
+    /// A [NixCmdError]
     #[error(transparent)]
     NixCmdError(#[from] NixCmdError),
 
+    /// nix-store returned "unknown-deriver"
     #[error("Unknown deriver")]
     UnknownDeriver,
 }

crates/nix_rs/src/store/mod.rs

@@ -1,3 +1,4 @@
+//! Dealing with the Nix store
 pub mod command;
 pub mod path;
 pub mod uri;

crates/nix_rs/src/store/path.rs

@@ -1,4 +1,4 @@
-/// Store path management
+//! Store path management
 use std::{convert::Infallible, fmt, path::PathBuf, str::FromStr};
 
 use serde_with::{DeserializeFromStr, SerializeDisplay};
@@ -30,6 +30,7 @@ impl From<&StorePath> for PathBuf {
 }
 
 impl StorePath {
+    /// Create a new `StorePath` from the given path
     pub fn new(path: PathBuf) -> Self {
         if path.ends_with(".drv") {
             StorePath::Drv(path)
@@ -38,6 +39,7 @@ impl StorePath {
         }
     }
 
+    /// Drop store path type distinction, returning the inner path.
     pub fn as_path(&self) -> &PathBuf {
         match self {
             StorePath::Drv(p) => p,

crates/nix_rs/src/store/uri.rs

@@ -1,4 +1,4 @@
-/// Store URI management
+//! Store URI management
 use std::{fmt, str::FromStr};
 
 use serde::{Deserialize, Serialize};
@@ -20,17 +20,24 @@ pub struct SSHStoreURI {
     pub host: String,
 }
 
+/// Error parsing a store URI
 #[derive(Error, Debug)]
 pub enum StoreURIParseError {
+    /// Invalid URI format
     #[error("Invalid URI format")]
     InvalidFormat,
+    /// Unsupported scheme
     #[error("Unsupported scheme: {0}")]
     UnsupportedScheme(String),
+    /// Missing host
     #[error("Missing host")]
     MissingHost,
 }
 
 impl StoreURI {
+    /// Parse a Nix store URI
+    ///
+    /// Currently only supports `ssh` scheme
     pub fn parse(uri: &str) -> Result<Self, StoreURIParseError> {
         let (scheme, rest) = uri
             .split_once("://")

crates/nix_rs/src/system_list.rs

@@ -8,7 +8,7 @@ use crate::{
 use lazy_static::lazy_static;
 
 lazy_static! {
-    /// As a HashMap<String, String>
+    /// Builtin list of [SystemsListFlakeRef]
     pub static ref NIX_SYSTEMS: HashMap<String, FlakeUrl> = {
         serde_json::from_str(env!("NIX_SYSTEMS")).unwrap()
     };
@@ -19,6 +19,7 @@ lazy_static! {
 pub struct SystemsListFlakeRef(pub FlakeUrl);
 
 impl SystemsListFlakeRef {
+    /// Lookup a known [SystemListFlakeRef] that will not require network calls
     pub fn from_known_system(system: &System) -> Option<Self> {
         NIX_SYSTEMS
             .get(&system.to_string())

crates/nix_rs/src/version.rs

@@ -12,17 +12,26 @@ use crate::command::{NixCmd, NixCmdError};
 /// Nix version as parsed from `nix --version`
 #[derive(Clone, Copy, PartialOrd, PartialEq, Eq, Debug, SerializeDisplay, DeserializeFromStr)]
 pub struct NixVersion {
+    /// Major version
     pub major: u32,
+    /// Minor version
     pub minor: u32,
+    /// Patch version
     pub patch: u32,
 }
 
+/// Error type for parsing `nix --version`
 #[derive(Error, Debug, Clone, PartialEq)]
 pub enum BadNixVersion {
+    /// Regex error
     #[error("Regex error: {0}")]
     Regex(#[from] regex::Error),
+
+    /// Parse error
     #[error("Parse error (regex): `nix --version` cannot be parsed")]
     Parse(#[from] std::num::ParseIntError),
+
+    /// Command error
     #[error("Parse error (int): `nix --version` cannot be parsed")]
     Command,
 }

crates/omnix-cli/crate.nix

@@ -1,12 +1,10 @@
-{ flake
-, rust-project
+{ rust-project
 , pkgs
 , lib
 , ...
 }:
 
 let
-  inherit (flake) inputs;
   inherit (pkgs) stdenv pkgsStatic;
 in
 {

crates/omnix-cli/tests/flake.nix

@@ -14,7 +14,7 @@
   outputs = inputs:
     inputs.flake-parts.lib.mkFlake { inherit inputs; } {
       systems = import inputs.systems;
-      perSystem = { pkgs, system, ... }: {
+      perSystem = { system, ... }: {
         packages = {
           haskell-multi-nix = inputs.haskell-multi-nix.packages.${system}.default;
         };

nix/modules/devshell.nix

@@ -1,4 +1,4 @@
-{ inputs, ... }:
+{ ... }:
 
 let
   root = ../..;
@@ -8,7 +8,7 @@ in
     (root + /crates/nix_health/module/flake-module.nix)
   ];
 
-  perSystem = { config, self', inputs', pkgs, lib, ... }: {
+  perSystem = { config, self', pkgs, ... }: {
     devShells.default = pkgs.mkShell {
       name = "omnix-devshell";
       meta.description = "Omnix development environment";