Documentation with rustdoc

//! # shelf-core
//!
//! Domain types for the *shelf* library catalogue: books, ISBNs, loans, and the
//! [`Catalog`] trait with an in-memory implementation.
//!
//! ```
//! use shelf_core::{Catalog, InMemoryCatalog};
//! let catalog = InMemoryCatalog::new();
//! assert!(catalog.is_empty());
//! ```

/// A validated ISBN-13, stored without hyphens.
///
/// Construct one with [`Isbn::parse`]; the type guarantees that every value has
/// 13 digits and a correct check digit.
///
/// # Examples
///
/// ```
/// use shelf_core::Isbn;
///
/// let isbn = Isbn::parse("978-0-441-01359-3")?;
/// assert_eq!(isbn.as_str(), "9780441013593");
/// # Ok::<(), shelf_core::IsbnError>(())
/// ```
pub struct Isbn(String);

/// Lends the book with `isbn` to `member`.
///
/// # Errors
///
/// Returns [`CatalogError::NotFound`] if the ISBN is unknown and
/// [`CatalogError::AlreadyLent`] if another member has the book.
///
/// # Panics
///
/// Panics if `member` is empty.
pub fn lend(isbn: &str, member: &str) -> Result<(), CatalogError> {
    assert!(!member.is_empty(), "member must not be empty");
    if isbn.is_empty() {
        return Err(CatalogError::NotFound);
    }
    Ok(())
}

/// Errors returned by [`lend`].
#[derive(Debug, PartialEq)]
pub enum CatalogError {
    /// No book with that ISBN.
    NotFound,
    /// The book is already on loan.
    AlreadyLent,
}

/// Reads `len` bytes starting at `ptr`.
///
/// # Safety
///
/// `ptr` must be valid for reads of `len` bytes and properly aligned, and the memory
/// must not be mutated for the lifetime of the returned slice.
pub unsafe fn bytes_at<'a>(ptr: *const u8, len: usize) -> &'a [u8] {
    // SAFETY: the caller guarantees the conditions documented above.
    unsafe { std::slice::from_raw_parts(ptr, len) }
}

fn main() {
    assert_eq!(lend("", "alice"), Err(CatalogError::NotFound));
    let data = [1u8, 2, 3];
    // SAFETY: `data` is a live array of 3 bytes.
    println!("{:?}", unsafe { bytes_at(data.as_ptr(), 3) });
}

/// Parses a year printed on a title page.
///
/// ```
/// # use doccheck::parse_year; // hidden line: still compiled
/// assert_eq!(parse_year("© 1965"), Some(1965));
/// ```
///
/// Years before printing are rejected:
///
/// ```should_panic
/// # use doccheck::parse_year;
/// parse_year("1066").expect("printed books only");
/// ```
///
/// A year is a number, not a string:
///
/// ```compile_fail
/// let y: u16 = doccheck::parse_year("1965"); // Option<u16> is not u16
/// ```
pub fn parse_year(text: &str) -> Option<u16> {
    let digits: String = text.chars().filter(char::is_ascii_digit).collect();
    digits.parse().ok().filter(|y| *y >= 1450)
}

cargo test --doc
#    Doc-tests doccheck
# running 3 tests
# test src/lib.rs - parse_year (line 3) ... ok
# test src/lib.rs - parse_year (line 10) - should panic ... ok
# test src/lib.rs - parse_year (line 17) - compile fail ... ok

cargo doc --open                    # build docs for your crate and all dependencies, open in a browser
cargo doc --no-deps                 # only your crate(s)
cargo doc --document-private-items  # include private items (for maintainers)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps   # fail CI on broken links and other rustdoc warnings