Document all library types

Author: phil-opp

src/args.rs

@@ -1,3 +1,5 @@
+//! Parses command line arguments.
+
 use crate::{config::Config, Command, ErrorMessage};
 use std::path::{Path, PathBuf};
 use std::{env, mem};

src/builder.rs

@@ -1,15 +1,21 @@
+//! Provides functions to build the kernel and the bootloader.
+
 use std::{
     fmt, fs, io,
     path::{Path, PathBuf},
     process::{self, Command},
 };
 
+/// Abstracts a build environment and provides methods for building the kernel and creating a
+/// bootimage.
 pub struct Builder {
     kernel_manifest_path: PathBuf,
     kernel_metadata: cargo_metadata::Metadata,
 }
 
 impl Builder {
+    /// Creates a new Builder by searching for the kernel's Cargo manifest and running
+    /// `cargo metadata` on it.
     pub fn new(manifest_path: Option<PathBuf>) -> Result<Self, BuilderError> {
         let kernel_manifest_path =
             manifest_path.unwrap_or(locate_cargo_manifest::locate_manifest()?);
@@ -22,20 +28,24 @@ impl Builder {
         })
     }
 
+    /// Returns the path to the `Cargo.toml` file of the kernel.
     pub fn kernel_manifest_path(&self) -> &Path {
         &self.kernel_manifest_path
     }
 
+    /// Returns the directory that contains the `Cargo.toml` of the kernel.
     pub fn kernel_root(&self) -> &Path {
         self.kernel_manifest_path
             .parent()
             .expect("kernel manifest has no parent directory")
     }
 
+    /// Returns a reference to the cargo metadata object.
     pub fn kernel_metadata(&self) -> &cargo_metadata::Metadata {
         &self.kernel_metadata
     }
 
+    /// Returns a reference to the kernel package in the `cargo metadata` output.
     pub fn kernel_package(&self) -> Result<&cargo_metadata::Package, String> {
         let mut packages = self.kernel_metadata.packages.iter();
         let kernel_package = packages.find(|p| &p.manifest_path == &self.kernel_manifest_path);
@@ -45,6 +55,12 @@ impl Builder {
         ))
     }
 
+    /// Builds the kernel by executing `cargo xbuild` with the given arguments.
+    ///
+    /// Returns a list of paths to all built executables. For crates with only a single binary,
+    /// the returned list contains only a single element.
+    ///
+    /// If the quiet argument is set to true, all output to stdout is suppressed.
     pub fn build_kernel(
         &self,
         args: &[String],
@@ -110,6 +126,11 @@ impl Builder {
         Ok(executables)
     }
 
+    /// Creates a bootimage by combining the given kernel binary with the bootloader.
+    ///
+    /// Places the resulting bootable disk image at the given `output_bin_path`.
+    ///
+    /// If the quiet argument is set to true, all output to stdout is suppressed.
     pub fn create_bootimage(
         &self,
         kernel_bin_path: &Path,
@@ -284,6 +305,7 @@ impl Builder {
     }
 }
 
+/// Represents an error that occurred while creating a new `Builder`.
 #[derive(Debug)]
 pub enum BuilderError {
     /// Failed to locate cargo manifest
@@ -309,6 +331,7 @@ impl fmt::Display for BuilderError {
     }
 }
 
+/// Represents an error that occurred when building the kernel.
 #[derive(Debug)]
 pub enum BuildKernelError {
     /// Could not find kernel package in cargo metadata, required for retrieving kernel crate name
@@ -320,11 +343,16 @@ pub enum BuildKernelError {
         /// The I/O error that occured
         error: io::Error,
     },
+    /// Could not find the `cargo xbuild` tool. Perhaps it is not installed?
     XbuildNotFound,
+    /// Running `cargo xbuild` failed.
     XbuildFailed {
+        /// The standard error output.
         stderr: Vec<u8>,
     },
+    /// The output of `cargo xbuild --message-format=json` was not valid UTF-8
     XbuildJsonOutputInvalidUtf8(std::string::FromUtf8Error),
+    /// The output of `cargo xbuild --message-format=json` was not valid JSON
     XbuildJsonOutputInvalidJson(json::Error),
     #[doc(hidden)]
     __NonExhaustive,
@@ -357,6 +385,7 @@ impl fmt::Display for BuildKernelError {
     }
 }
 
+/// Represents an error that occurred when creating a bootimage.
 #[derive(Debug)]
 pub enum CreateBootimageError {
     /// Could not find some required information in the `cargo metadata` output
@@ -368,7 +397,9 @@ pub enum CreateBootimageError {
     BootloaderNotFound,
     /// Bootloader dependency has not the right format
     BootloaderInvalid(String),
+    /// Building the bootloader failed
     BootloaderBuildFailed {
+        /// The `cargo xbuild` output to standard error
         stderr: Vec<u8>,
     },
     /// An unexpected I/O error occurred
@@ -384,9 +415,12 @@ pub enum CreateBootimageError {
     LlvmObjcopyNotFound,
     /// The `llvm-objcopy` command failed
     ObjcopyFailed {
+        /// The output of `llvm-objcopy` to standard error
         stderr: Vec<u8>,
     },
+    /// The output of `cargo xbuild --message-format=json` was not valid UTF-8
     XbuildJsonOutputInvalidUtf8(std::string::FromUtf8Error),
+    /// The output of `cargo xbuild --message-format=json` was not valid JSON
     XbuildJsonOutputInvalidJson(json::Error),
     #[doc(hidden)]
     __NonExhaustive,

src/config.rs

@@ -1,12 +1,25 @@
+//! Parses the `package.metadata.bootimage` configuration table
+
 use crate::ErrorMessage;
 use std::path::Path;
 use toml::Value;
 
+/// Represents the `package.metadata.bootimage` configuration table
+///
+/// The bootimage crate can be configured through a `package.metadata.bootimage` table
+/// in the `Cargo.toml` file of the kernel. This struct represents the parsed configuration
+/// options.
 #[derive(Debug, Clone)]
 pub struct Config {
+    /// This target is used if no `--target` argument is passed
     pub default_target: Option<String>,
+    /// The run command that is invoked on `bootimage run` or `bootimage runner`
+    ///
+    /// The substring "{}" will be replaced with the path to the bootable disk image.
     pub run_command: Vec<String>,
+    /// Additional arguments passed to the runner on `bootimage run` or `bootimage runner`
     pub run_args: Option<Vec<String>>,
+    /// The timeout for running an integration test through `bootimage test` in seconds
     pub test_timeout: u32,
     non_exhaustive: (),
 }

src/lib.rs

@@ -1,8 +1,14 @@
+//! Provides functions to create a bootable OS image from a kernel binary.
+//!
+//! This crate is mainly built as a binary tool. Run `cargo install bootimage` to install it.
+
+#![warn(missing_docs)]
+
 use args::{Args, RunnerArgs};
 use std::{fmt, process};
 
-pub mod builder;
 mod args;
+pub mod builder;
 pub mod config;
 pub mod help;
 
@@ -23,6 +29,13 @@ enum Command {
     Version,
 }
 
+/// The entry point for the binaries.
+///
+/// We support two binaries, `bootimage` and `cargo-bootimage` that both just
+/// call into this function.
+///
+/// This function is just a small wrapper around [`run`] that prints error messages
+/// and exits with the correct exit code.
 pub fn lib_main() {
     match run() {
         Err(err) => {
@@ -36,6 +49,13 @@ pub fn lib_main() {
     }
 }
 
+/// Run the invoked command.
+///
+/// This function parses the arguments and invokes the chosen subcommand.
+///
+/// On success, it optionally returns an exit code. This feature is used by the
+/// `run` and `runner` subcommand to pass through the exit code of the invoked
+/// run command.
 pub fn run() -> Result<Option<i32>, ErrorMessage> {
     let command = args::parse_args()?;
     let none = |()| None;
@@ -54,7 +74,12 @@ pub fn run() -> Result<Option<i32>, ErrorMessage> {
     }
 }
 
+/// A simple error message that can be created from every type that implements `fmt::Display`.
+///
+/// We use this error type for the CLI interface, where text based, human readable error messages
+/// make sense. For the library part of this crate, we use custom error enums.
 pub struct ErrorMessage {
+    /// The actual error message
     pub message: Box<dyn fmt::Display + Send>,
 }