Merge pull request #138 from rust-embedded-community/clean-up-docs

Minor clean-ups of docs.

LICENSE-MIT

@@ -1,4 +1,5 @@
-Copyright (c) 2018-2023 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2011-2018 Bill Greiman
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

NOTICE

@@ -0,0 +1,6 @@
+# Copyright Notices
+
+This is a copyright notices file, as described by the Apache-2.0 license.
+
+Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2011-2018 Bill Greiman

README.md

@@ -59,10 +59,12 @@ let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(blo
 * Log over defmt or the common log interface (feature flags).
 
 ## No-std usage
+
 This repository houses no examples for no-std usage, however you can check out the following examples:
-- [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs)
-- [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs)
-- [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs)
+
+* [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs)
+* [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs)
+* [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs)
 
 ## Todo List (PRs welcome!)
 
@@ -79,12 +81,14 @@ The changelog has moved to [CHANGELOG.md](/CHANGELOG.md)
 Licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  http://www.apache.org/licenses/LICENSE-2.0)
+  <http://www.apache.org/licenses/LICENSE-2.0>)
 
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
 
 at your option.
 
+Copyright notices are stored in the [NOTICE](./NOTICE) file.
+
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally

src/blockdevice.rs

@@ -1,11 +1,12 @@
-//! Block Device support
+//! Traits and types for working with Block Devices.
 //!
 //! Generic code for handling block devices, such as types for identifying
 //! a particular block on a block device by its index.
 
-/// Represents a standard 512 byte block (also known as a sector). IBM PC
-/// formatted 5.25" and 3.5" floppy disks, SD/MMC cards up to 1 GiB in size
-/// and IDE/SATA Hard Drives up to about 2 TiB all have 512 byte blocks.
+/// A standard 512 byte block (also known as a sector).
+///
+/// IBM PC formatted 5.25" and 3.5" floppy disks, IDE/SATA Hard Drives up to
+/// about 2 TiB, and almost all SD/MMC cards have 512 byte blocks.
 ///
 /// This library does not support devices with a block size other than 512
 /// bytes.
@@ -15,15 +16,17 @@ pub struct Block {
     pub contents: [u8; Block::LEN],
 }
 
-/// Represents the linear numeric address of a block (or sector). The first
-/// block on a disk gets `BlockIdx(0)` (which usually contains the Master Boot
-/// Record).
+/// The linear numeric address of a block (or sector).
+///
+/// The first block on a disk gets `BlockIdx(0)` (which usually contains the
+/// Master Boot Record).
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct BlockIdx(pub u32);
 
-/// Represents the a number of blocks (or sectors). Add this to a `BlockIdx`
-/// to get an actual address on disk.
+/// The a number of blocks (or sectors).
+///
+/// Add this to a `BlockIdx` to get an actual address on disk.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct BlockCount(pub u32);
@@ -34,7 +37,7 @@ pub struct BlockIter {
     current: BlockIdx,
 }
 
-/// Represents a block device - a device which can read and write blocks (or
+/// A block device - a device which can read and write blocks (or
 /// sectors). Only supports devices which are <= 2 TiB in size.
 pub trait BlockDevice {
     /// The errors that the `BlockDevice` can return. Must be debug formattable.

src/fat/bpb.rs

@@ -6,9 +6,10 @@ use crate::{
 };
 use byteorder::{ByteOrder, LittleEndian};
 
-/// Represents a Boot Parameter Block. This is the first sector of a FAT
-/// formatted partition, and it describes various properties of the FAT
-/// filesystem.
+/// A Boot Parameter Block.
+///
+/// This is the first sector of a FAT formatted partition, and it describes
+/// various properties of the FAT filesystem.
 pub struct Bpb<'a> {
     data: &'a [u8; 512],
     pub(crate) fat_type: FatType,

src/fat/ondiskdirentry.rs

@@ -3,7 +3,10 @@
 use crate::{fat::FatType, Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp};
 use byteorder::{ByteOrder, LittleEndian};
 
-/// Represents a 32-byte directory entry as stored on-disk in a directory file.
+/// A 32-byte directory entry as stored on-disk in a directory file.
+///
+/// This is the same for FAT16 and FAT32 (except FAT16 doesn't use
+/// first_cluster_hi).
 pub struct OnDiskDirEntry<'a> {
     data: &'a [u8],
 }
@@ -38,8 +41,6 @@ impl<'a> core::fmt::Debug for OnDiskDirEntry<'a> {
     }
 }
 
-/// Represents the 32 byte directory entry. This is the same for FAT16 and
-/// FAT32 (except FAT16 doesn't use first_cluster_hi).
 impl<'a> OnDiskDirEntry<'a> {
     pub(crate) const LEN: usize = 32;
     pub(crate) const LEN_U32: u32 = 32;

src/filesystem/directory.rs

@@ -7,8 +7,7 @@ use crate::{Error, RawVolume, VolumeManager};
 
 use super::ToShortFileName;
 
-/// Represents a directory entry, which tells you about
-/// other files and directories.
+/// A directory entry, which tells you about other files and directories.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct DirEntry {
@@ -30,7 +29,7 @@ pub struct DirEntry {
     pub entry_offset: u32,
 }
 
-/// Represents an open directory on disk.
+/// A handle for an open directory on disk.
 ///
 /// Do NOT drop this object! It doesn't hold a reference to the Volume Manager
 /// it was created from and if you drop it, the VolumeManager will think you
@@ -70,7 +69,7 @@ impl RawDirectory {
     }
 }
 
-/// Represents an open directory on disk.
+/// A handle for an open directory on disk, which closes on drop.
 ///
 /// In contrast to a `RawDirectory`, a `Directory` holds a mutable reference to
 /// its parent `VolumeManager`, which restricts which operations you can perform.

src/filesystem/files.rs

@@ -3,7 +3,7 @@ use crate::{
     Error, RawVolume, VolumeManager,
 };
 
-/// Represents an open file on disk.
+/// A handle for an open file on disk.
 ///
 /// Do NOT drop this object! It doesn't hold a reference to the Volume Manager
 /// it was created from and cannot update the directory entry if you drop it.
@@ -37,7 +37,7 @@ impl RawFile {
     }
 }
 
-/// Represents an open file on disk.
+/// A handle for an open file on disk, which closes on drop.
 ///
 /// In contrast to a `RawFile`, a `File`  holds a mutable reference to its
 /// parent `VolumeManager`, which restricts which operations you can perform.

src/filesystem/timestamp.rs

@@ -4,9 +4,10 @@ pub trait TimeSource {
     fn get_timestamp(&self) -> Timestamp;
 }
 
-/// Represents an instant in time, in the local time zone. TODO: Consider
-/// replacing this with POSIX time as a `u32`, which would save two bytes at
-/// the expense of some maths.
+/// A Gregorian Calendar date/time, in the local time zone.
+///
+/// TODO: Consider replacing this with POSIX time as a `u32`, which would save
+/// two bytes at the expense of some maths.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Copy, Clone, PartialOrd, Ord, PartialEq, Eq)]
 pub struct Timestamp {

src/lib.rs

@@ -135,7 +135,7 @@ macro_rules! warn {
 //
 // ****************************************************************************
 
-/// Represents all the ways the functions in this crate can fail.
+/// All the ways the functions in this crate can fail.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Clone)]
 pub enum Error<E>
@@ -211,7 +211,7 @@ where
     }
 }
 
-/// Represents a partition with a filesystem within it.
+/// A partition with a filesystem within it.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct RawVolume(SearchId);
@@ -236,7 +236,7 @@ impl RawVolume {
     }
 }
 
-/// Represents an open volume on disk.
+/// An open volume on disk, which closes on drop.
 ///
 /// In contrast to a `RawVolume`, a `Volume` holds a mutable reference to its
 /// parent `VolumeManager`, which restricts which operations you can perform.
@@ -354,8 +354,7 @@ pub enum VolumeType {
     Fat(FatVolume),
 }
 
-/// A `VolumeIdx` is a number which identifies a volume (or partition) on a
-/// disk.
+/// A number which identifies a volume (or partition) on a disk.
 ///
 /// `VolumeIdx(0)` is the first primary partition on an MBR partitioned disk.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]

src/sdcard/mod.rs

@@ -1,6 +1,4 @@
-//! The SD/MMC Protocol
-//!
-//! Implements the SD/MMC protocol on some generic SPI interface.
+//! Implements the BlockDevice trait for an SD/MMC Protocol over SPI.
 //!
 //! This is currently optimised for readability and debugability, not
 //! performance.
@@ -21,7 +19,7 @@ use crate::{debug, warn};
 // Types and Implementations
 // ****************************************************************************
 
-/// Represents an SD Card on an SPI bus.
+/// Driver for an SD Card on an SPI bus.
 ///
 /// Built from an [`SpiDevice`] implementation and a Chip Select pin.
 ///
@@ -201,7 +199,7 @@ where
     }
 }
 
-/// Represents an SD Card on an SPI bus.
+/// Inner details for the SD Card driver.
 ///
 /// All the APIs required `&mut self`.
 struct SdCardInner<SPI, DELAYER>

src/volume_mgr.rs

@@ -18,8 +18,11 @@ use crate::{
 };
 use heapless::Vec;
 
-/// A `VolumeManager` wraps a block device and gives access to the FAT-formatted
-/// volumes within it.
+/// Wraps a block device and gives access to the FAT-formatted volumes within
+/// it.
+///
+/// Tracks which files and directories are open, to prevent you from deleting
+/// a file or directory you currently have open.
 #[derive(Debug)]
 pub struct VolumeManager<
     D,