docs: add missing docs & fix already-existing ones

src/fs.rs

@@ -149,7 +149,7 @@ impl BootRecordFAT {
 
 #[derive(Debug, Clone, Copy)]
 #[repr(packed)]
-// Everything here is naturally aligned (thank god), so there's no need to make this a packed struct
+// Everything here is naturally aligned (thank god)
 struct BootRecordExFAT {
     _dummy_jmp: [u8; 3],
     _oem_identifier: [u8; 8],
@@ -247,6 +247,8 @@ struct FSInfoFAT32 {
 
 /// An enum representing different versions of the FAT filesystem
 #[derive(Debug, Clone, Copy, PartialEq)]
+// no need for enum variant documentation here
+#[allow(missing_docs)]
 pub enum FATType {
     FAT12,
     FAT16,
@@ -256,6 +258,7 @@ pub enum FATType {
 
 impl FATType {
     #[inline]
+    /// How many bits this [`FATType`] uses to address clusters in the disk
     pub fn bits_per_entry(&self) -> u8 {
         match self {
             FATType::FAT12 => 12,
@@ -533,31 +536,45 @@ pub struct Properties {
 /// Getter methods
 impl Properties {
     #[inline]
+    /// Get the corresponding [`PathBuf`] to this entry
     pub fn path(&self) -> &PathBuf {
         &self.path
     }
 
     #[inline]
+    /// Get the corresponding [`Attributes`] to this entry
     pub fn attributes(&self) -> &Attributes {
         &self.attributes
     }
 
     #[inline]
+    /// Find out when this entry was created (max resolution: 1ms)
+    ///
+    /// Returns a [`PrimitiveDateTime`] from the [`time`] crate
     pub fn creation_time(&self) -> &PrimitiveDateTime {
         &self.created
     }
 
     #[inline]
+    /// Find out when this entry was last modified (max resolution: 2 secs)
+    ///
+    /// Returns a [`PrimitiveDateTime`] from the [`time`] crate
     pub fn modification_time(&self) -> &PrimitiveDateTime {
         &self.modified
     }
 
     #[inline]
+    /// Find out when this entry was last accessed (max resolution: 1 day)
+    ///
+    /// Returns a [`Date`] from the [`time`] crate
     pub fn last_accessed_date(&self) -> &Date {
         &self.accessed
     }
 
     #[inline]
+    /// Find out the size of this entry
+    ///
+    /// Always returns `0` for directories
     pub fn file_size(&self) -> u32 {
         self.file_size
     }

src/io.rs

@@ -1,4 +1,16 @@
 //! This module contains all the IO-related objects of the crate
+//!
+//! If you want to implement IO functionality in a `std` environment,
+//! it is advised to implement the relevant [`std::io`] traits, which will
+//! auto-`impl` the corresponding IO traits here. In a `no-std` environment,
+//! implement the traits directly
+//!
+//! # Traits
+//!
+//! - [`IOBase`] provides a common error type for [`Read`], [`Write`] & [`Seek`]
+//! - [`Read`] allows for reading bytes from a source.
+//! - [`Write`] allows for writing bytes to a sink.
+//! - [`Seek`] provides a cursor which can be moved within a stream of bytes
 
 #[cfg(not(feature = "std"))]
 use core::*;
@@ -53,6 +65,8 @@ pub trait Read: IOBase {
     /// `buf`. This function will continuously call [`read()`] to append more data to
     /// `buf` until [`read()`] returns either [`Ok(0)`] or an [`IOErrorKind`] of
     /// non-`Interrupted` kind.
+    ///
+    /// [`read()`]: Read::read
     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Self::Error> {
         let mut bytes_read = 0;
 
@@ -157,18 +171,18 @@ pub trait Write: IOBase {
     /// Attempts to write an entire buffer into this writer.
     ///
     /// This method will continuously call [`write`] until there is no more data
-    /// to be written or an error of non-[`ErrorKind::Interrupted`] kind is
+    /// to be written or an error of non-`Interrupted` [`IOErrorKind`] is
     /// returned. This method will not return until the entire buffer has been
     /// successfully written or such an error occurs. The first error that is
-    /// not of [`ErrorKind::Interrupted`] kind generated from this method will be
+    /// not of `Interrupted` [`IOErrorKind`] generated from this method will be
     /// returned.
     ///
     /// If the buffer contains no data, this will never call [`write`].
     ///
     /// # Errors
     ///
     /// This function will return the first error of
-    /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns.
+    /// non-`Interrupted` [`IOErrorKind`] that [`write`] returns.
     ///
     /// [`write`]: Write::write
     fn write_all(&mut self, mut buf: &[u8]) -> Result<(), Self::Error> {

src/lib.rs

@@ -1,6 +1,56 @@
+//! # simple-fatfs
+//!
+//! An easy-to-use FAT filesystem library designed for usage in embedded systems
+//!
+//! ## Features
+//!
+//! - `no_std` support
+//! - FAT12/16/32 support
+//! - VFAT/LFN (long filenames) support
+//! - Auto-`impl`s for [`std::io`] traits and structs
+//! - Easy-to-implement [`io`] traits
+//!
+//! # Examples
+//! ```
+//! extern crate simple_fatfs;
+//! use simple_fatfs::*;
+//! use simple_fatfs::io::prelude::*;
+//!
+//! const FAT_IMG: &[u8] = include_bytes!("../imgs/fat12.img");
+//!
+//! fn main() {
+//!     let mut cursor = std::io::Cursor::new(FAT_IMG.to_owned());
+//!
+//!     // We can either pass by value of by (mutable) reference
+//!     let mut fs = FileSystem::from_storage(&mut cursor).unwrap();
+//!
+//!     // Let's see what entries are in the root directory
+//!     for entry in fs.read_dir(PathBuf::from("/")).unwrap() {
+//!         if entry.path().is_dir() {
+//!             println!("Directory: {}", entry.path())
+//!         } else if entry.path().is_file() {
+//!             println!("File: {}", entry.path())
+//!         } else {
+//!             unreachable!()
+//!         }
+//!     }
+//!
+//!     // the image we currently use has a file named "root.txt"
+//!     // in the root directory. Let's read it
+//!
+//!     // please keep in mind that opening a `File` borrows
+//!     // the parent `FileSystem` until that `File` is dropped
+//!     let mut file = fs.get_file(PathBuf::from("/root.txt")).unwrap();
+//!     let mut string = String::new();
+//!     file.read_to_string(&mut string);
+//!     println!("root.txt contents:\n{}", string);
+//! }
+//! ```
+
 #![cfg_attr(not(feature = "std"), no_std)]
 // Even inside unsafe functions, we must acknowlegde the usage of unsafe code
 #![deny(unsafe_op_in_unsafe_fn)]
+#![deny(missing_docs)]
 
 extern crate alloc;