kernel: Add docstrings

Assisted-by: Claude Code
Signed-off-by: Colin Walters <[email protected]>

Author: cgwalters

crates/lib/src/kernel.rs

@@ -1,3 +1,8 @@
+//! Kernel command line parsing utilities.
+//!
+//! This module provides functionality for parsing and working with kernel command line
+//! arguments, supporting both key-only switches and key-value pairs with proper quote handling.
+
 use std::borrow::Cow;
 
 use anyhow::Result;
@@ -7,19 +12,35 @@ pub(crate) const INITRD_ARG_PREFIX: &[u8] = b"rd.";
 /// The kernel argument for configuring the rootfs flags.
 pub(crate) const ROOTFLAGS: &[u8] = b"rootflags";
 
+/// A parsed kernel command line.
+///
+/// Wraps the raw command line bytes and provides methods for parsing and iterating
+/// over individual parameters. Uses copy-on-write semantics to avoid unnecessary
+/// allocations when working with borrowed data.
 pub(crate) struct Cmdline<'a>(Cow<'a, [u8]>);
 
 impl<'a, T: AsRef<[u8]> + ?Sized> From<&'a T> for Cmdline<'a> {
+    /// Creates a new `Cmdline` from any type that can be referenced as bytes.
+    ///
+    /// Uses borrowed data when possible to avoid unnecessary allocations.
     fn from(input: &'a T) -> Self {
         Self(Cow::Borrowed(input.as_ref()))
     }
 }
 
 impl<'a> Cmdline<'a> {
+    /// Reads the kernel command line from `/proc/cmdline`.
+    ///
+    /// Returns an error if the file cannot be read or if there are I/O issues.
     pub fn from_proc() -> Result<Self> {
         Ok(Self(Cow::Owned(std::fs::read("/proc/cmdline")?)))
     }
 
+    /// Returns an iterator over all parameters in the command line.
+    ///
+    /// Properly handles quoted values containing whitespace and splits on
+    /// unquoted whitespace characters. Parameters are parsed as either
+    /// key-only switches or key=value pairs.
     pub fn iter(&'a self) -> impl Iterator<Item = Parameter<'a>> {
         let mut in_quotes = false;
 
@@ -34,29 +55,50 @@ impl<'a> Cmdline<'a> {
     }
 
     /// Locate a kernel argument with the given key name.
+    ///
+    /// Returns the first parameter matching the given key, or `None` if not found.
+    /// Key comparison treats dashes and underscores as equivalent.
     pub fn find(&'a self, key: impl AsRef<[u8]>) -> Option<Parameter<'a>> {
         let key = key.as_ref();
         self.iter().find(|p| p.key == key)
     }
 }
 
+/// A single kernel command line parameter.
+///
+/// Can represent either a simple switch (key only) or a key-value pair.
+/// Handles quoted values and treats dashes and underscores in keys as equivalent.
 #[derive(Debug, Eq)]
 pub(crate) struct Parameter<'a> {
+    /// The parameter key as raw bytes
     pub key: &'a [u8],
+    /// The parameter value as raw bytes, if present
     pub value: Option<&'a [u8]>,
 }
 
 impl<'a> Parameter<'a> {
+    /// Returns the key as a lossy UTF-8 string.
+    ///
+    /// Invalid UTF-8 sequences are replaced with the Unicode replacement character.
     pub fn key_lossy(&self) -> String {
         String::from_utf8_lossy(self.key).to_string()
     }
 
+    /// Returns the value as a lossy UTF-8 string.
+    ///
+    /// Invalid UTF-8 sequences are replaced with the Unicode replacement character.
+    /// Returns an empty string if no value is present.
     pub fn value_lossy(&self) -> String {
         String::from_utf8_lossy(self.value.unwrap_or(&[])).to_string()
     }
 }
 
 impl<'a, T: AsRef<[u8]> + ?Sized> From<&'a T> for Parameter<'a> {
+    /// Parses a parameter from raw bytes.
+    ///
+    /// Splits on the first `=` character to separate key and value.
+    /// Strips only the outermost pair of double quotes from values.
+    /// If no `=` is found, treats the entire input as a key-only parameter.
     fn from(input: &'a T) -> Self {
         let input = input.as_ref();
         let equals = input.iter().position(|b| *b == b'=');
@@ -90,6 +132,11 @@ impl<'a, T: AsRef<[u8]> + ?Sized> From<&'a T> for Parameter<'a> {
 }
 
 impl PartialEq for Parameter<'_> {
+    /// Compares two parameters for equality.
+    ///
+    /// Keys are compared with dashes and underscores treated as equivalent.
+    /// Values must match exactly if both are present, or both must be absent.
+    /// Prevents substring matching by ensuring full length equality.
     fn eq(&self, other: &Self) -> bool {
         let dedashed = |&c: &u8| {
             if c == b'-' {
@@ -118,6 +165,11 @@ impl PartialEq for Parameter<'_> {
 }
 
 impl std::fmt::Display for Parameter<'_> {
+    /// Formats the parameter for display.
+    ///
+    /// Key-only parameters are displayed as just the key.
+    /// Key-value parameters are displayed as `key=value`.
+    /// Values containing whitespace are automatically quoted.
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
         let key = self.key_lossy();