docs: add documentation to all the crates (#268)

crates/rattler/src/install/apple_codesign.rs

@@ -1,3 +1,5 @@
+//! Code signing for Apple Silicon binaries
+
 use super::LinkFileError;
 use std::path::Path;
 

crates/rattler/src/install/link.rs

@@ -1,3 +1,5 @@
+//! This module contains the logic to link a give file from the package cache into the target directory.
+//! See [`link_file`] for more information.
 use crate::install::python::PythonInfo;
 use rattler_conda_types::package::{FileMode, PathType, PathsEntry, PrefixPlaceholder};
 use rattler_conda_types::{NoArchType, Platform};
@@ -10,29 +12,39 @@ use std::path::{Path, PathBuf};
 
 use super::apple_codesign::{codesign, AppleCodeSignBehavior};
 
+/// Errors that can occur when calling [`link_file`].
 #[derive(Debug, thiserror::Error)]
 pub enum LinkFileError {
+    /// An IO error occurred.
     #[error(transparent)]
     IoError(#[from] std::io::Error),
 
+    /// The parent directory of the destination file could not be created.
     #[error("failed to create parent directory")]
     FailedToCreateParentDirectory(#[source] std::io::Error),
 
+    /// The source file could not be opened.
     #[error("could not open source file")]
     FailedToOpenSourceFile(#[source] std::io::Error),
 
+    /// The source file metadata could not be read.
     #[error("could not source file metadata")]
     FailedToReadSourceFileMetadata(#[source] std::io::Error),
 
+    /// The destination file could not be opened.
     #[error("could not open destination file for writing")]
     FailedToOpenDestinationFile(#[source] std::io::Error),
 
+    /// The permissions could not be updated on the destination file.
     #[error("could not update destination file permissions")]
     FailedToUpdateDestinationFilePermissions(#[source] std::io::Error),
 
+    /// The binary (dylib or executable) could not be signed (codesign -f -s -) on
+    /// macOS ARM64 (Apple Silicon).
     #[error("failed to sign Apple binary")]
     FailedToSignAppleBinary,
 
+    /// No Python version was specified when installing a noarch package.
     #[error("cannot install noarch python files because there is no python version specified ")]
     MissingPythonInfo,
 }

crates/rattler/src/install/mod.rs

@@ -1,3 +1,18 @@
+//! This module contains the logic to install a package into a prefix. The main entry point is the
+//! [`link_package`] function.
+//!
+//! The [`link_package`] function takes a package directory and a target directory. The package
+//! directory is the directory that contains the extracted package archive. The target directory is
+//! the directory into which the package should be installed. The target directory is also called
+//! the "prefix".
+//!
+//! The [`link_package`] function will read the `paths.json` file from the package directory and
+//! link all files specified in that file into the target directory. The `paths.json` file contains
+//! a list of files that should be installed and how they should be installed. For example, the
+//! `paths.json` file might contain a file that should be copied into the target directory. Or it
+//! might contain a file that should be linked into the target directory. The `paths.json` file
+//! also contains a SHA256 hash for each file. This hash is used to verify that the file was not
+//! tampered with.
 pub mod apple_codesign;
 mod driver;
 mod entry_point;
@@ -34,30 +49,39 @@ use tracing::instrument;
 /// An error that might occur when installing a package.
 #[derive(Debug, thiserror::Error)]
 pub enum InstallError {
+    /// The operation was cancelled.
     #[error("the operation was cancelled")]
     Cancelled,
 
+    /// The paths.json file could not be read.
     #[error("failed to read 'paths.json'")]
     FailedToReadPathsJson(#[source] std::io::Error),
 
+    /// The index.json file could not be read.
     #[error("failed to read 'index.json'")]
     FailedToReadIndexJson(#[source] std::io::Error),
 
+    /// The link.json file could not be read.
     #[error("failed to read 'link.json'")]
     FailedToReadLinkJson(#[source] std::io::Error),
 
+    /// A file could not be linked.
     #[error("failed to link '{0}'")]
     FailedToLink(PathBuf, #[source] LinkFileError),
 
+    /// The target prefix is not UTF-8.
     #[error("target prefix is not UTF-8")]
     TargetPrefixIsNotUtf8,
 
+    /// Failed to create the target directory.
     #[error("failed to create target directory")]
     FailedToCreateTargetDirectory(#[source] std::io::Error),
 
+    /// A noarch package could not be installed because no python version was specified.
     #[error("cannot install noarch python package because there is no python version specified")]
     MissingPythonInfo,
 
+    /// Failed to create a python entry point for a noarch package.
     #[error("failed to create Python entry point")]
     FailedToCreatePythonEntryPoint(#[source] std::io::Error),
 }

crates/rattler/src/lib.rs

@@ -8,6 +8,7 @@
 //! in a wide variaty of tools that do not rely on Python. Rust has excellent support for
 //! interfacing with many other languages (WASM, Javascript, Python, C, etc) and is therefor a good
 //! candidate for a reimplementation.
+#![deny(missing_docs)]
 
 use std::path::PathBuf;
 

crates/rattler/src/package_cache.rs

@@ -79,6 +79,7 @@ struct Package {
 /// An error that might be returned from one of the caching function of the [`PackageCache`].
 #[derive(Debug, Clone, thiserror::Error)]
 pub enum PackageCacheError {
+    /// An error occurred while fetching the package.
     #[error(transparent)]
     FetchError(#[from] Arc<dyn std::error::Error + Send + Sync + 'static>),
 }

crates/rattler/src/validation.rs

@@ -22,43 +22,55 @@ use std::{
 /// corrupted.
 #[derive(Debug, thiserror::Error)]
 pub enum PackageValidationError {
+    /// Neither a `paths.json` file nor a deprecated `files` file was found.
     #[error("neither a 'paths.json' or a deprecated 'files' file was found")]
     MetadataMissing,
 
+    /// An error occurred while reading the `paths.json` file.
     #[error("failed to read 'paths.json' file")]
     ReadPathsJsonError(#[source] std::io::Error),
 
+    /// An error occurred while reading the deprecated `files` file.
     #[error("failed to read validation data from deprecated files")]
     ReadDeprecatedPathsJsonError(#[source] std::io::Error),
 
+    /// The path seems to be corrupted.
     #[error("the path '{0}' seems to be corrupted")]
     CorruptedEntry(PathBuf, #[source] PackageEntryValidationError),
 
+    /// An error occurred while reading the `index.json` file.
     #[error("failed to read 'index.json'")]
     ReadIndexJsonError(#[source] std::io::Error),
 }
 
 /// An error that indicates that a specific file in a package archive directory seems to be corrupted.
 #[derive(Debug, thiserror::Error)]
 pub enum PackageEntryValidationError {
+    /// An error occurred while reading the metadata of the file.
     #[error("failed to retrieve file metadata'")]
     GetMetadataFailed(#[source] std::io::Error),
 
+    /// The file does not exist.
     #[error("the file does not exist")]
     NotFound,
 
+    /// The file is not a symbolic link.
     #[error("expected a symbolic link")]
     ExpectedSymlink,
 
+    /// The file is not a directory.
     #[error("expected a directory")]
     ExpectedDirectory,
 
+    /// The size of the file does not match the expected size.
     #[error("incorrect size, expected {0} but file on disk is {1}")]
     IncorrectSize(u64, u64),
 
+    /// An IO error occurred while reading the file.
     #[error("an io error occurred")]
     IoError(#[from] std::io::Error),
 
+    /// The SHA256 hash of the file does not match the expected hash.
     #[error("sha256 hash mismatch, expected '{0}' but file on disk is '{1}'")]
     HashMismatch(String, String),
 }

crates/rattler_macros/src/lib.rs

@@ -1,3 +1,7 @@
+//! Some macros for the Rattler project.
+
+#![deny(missing_docs)]
+
 use proc_macro::TokenStream;
 use quote::quote_spanned;
 use syn::{parse_macro_input, Data, DeriveInput, Fields, FieldsNamed, Ident};