In this example, you can see how we write our custom error types and are able to wrap errors that we receive from other functions in order to escalate them properly.

#![allow(unused)]
fn main() {
//! This module provides error types for the config parser.

use std::io::Error as IoError;
use std::{error::Error, fmt};
use toml::{de::Error as TomlDeError, ser::Error as TomlSeError};

/// All errors the config parser can encounter.
#[derive(Debug)]
pub enum ConfigError {
    /// Used for handling errors during file operations.
    FileOpError(IoError),
    /// Indicates that no config file has been found, or it has been moved or deleted during program startup.
    NoConfigFileError(String),
    /// Indicates that a required config option is missing from the config file.
    MissingConfigOptionError(String),
    /// Indicates an error during deserialization of the TOML config file.
    DeserializationError(TomlDeError),
    /// Indicates an error during Serialization of config parameters to a TOML value.
    SerializationError(TomlSeError),
    /// Expects a `String` message. Used for edge cases and general purpose error cases.
    Other(String),
}

impl fmt::Display for ConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ConfigError::FileOpError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m File operation failed: {err}")
            }
            ConfigError::NoConfigFileError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m No config file found: {err}")
            }
            ConfigError::MissingConfigOptionError(err) => {
                write!(
                    f,
                    "\x1b[31m[error]\x1b[0m Missing required config parameter: {err}"
                )
            }
            ConfigError::DeserializationError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Invalid config file: {err}")
            }
            ConfigError::SerializationError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Serialization error: {err}")
            }
            ConfigError::Other(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Config Parser error: {err}")
            }
        }
    }
}

impl Error for ConfigError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            ConfigError::FileOpError(err) => Some(err),
            ConfigError::NoConfigFileError(_) => None,
            ConfigError::MissingConfigOptionError(_) => None,
            ConfigError::DeserializationError(err) => Some(err),
            ConfigError::SerializationError(err) => Some(err),
            ConfigError::Other(_) => None,
        }
    }
}
}

Documenting Functions:

#![allow(unused)]
fn main() {
/// This function does X.
///
/// This function does X by doing Y using Z. (Detailed explanation optional)
///
/// # Parameters
/// * `arg: str` - A string argument to process
///
/// # Returns
/// * `Ok(str)` - Returns A, if ...
/// * `Err` - Returns an `ErrType`
pub fn foo(arg: str) -> Result<str, Err> {
 // ...
}
}

While not universally used by all projects, we use # Parameters and # Returns sections, especially for larger functions.

If a function does not take arguments, the # Parameters section can be omitted. However, if the function does not return (! type) - or returns (), this has to be indicated in the # Returns section.

Other sections we use are:

• # Aborts - If the function aborts the program. (E.g When input parameters are missing)
• # Panics - If the function can cause a panic!().

For both of these sections, list all - or at least the most common - reasons this behaviour can occur. This can help debugging immensely.

#![allow(unused)]
fn main() {
/// This function does X.
///
/// # Paramters
/// - `path: &str` - The path to a file
///
/// # Returns
/// - `String` - The contents of the file.
///
/// # Aborts
/// This function will exit the process if the file cannot be found.
pub fn read_file(path: &str) -> String {
    match fs::read_to_string(path) {
        Ok(contents) => contents,
        Err(err) => {
            eprintln!("[Error] File '{}' does not exist: {}", path, err);
            process::exit(1);
        }
    }
}
}

Documenting Structs:

#![allow(unused)]
fn main() {
/// Information about a Person.
pub struct Person {
    /// The name of the Person.
    pub name: String,
    /// The age of the Person.
    pub age: i64,
}
}

It is encouraged to briefly document every field of your struct, whether they are pub or not does not matter.

Documenting Modules:

#![allow(unused)]
fn main() {
//! This module handles X.
}

You can go into depth here about what a module does. This is encouraged for larger modules.