Improve docs

README.md

@@ -34,12 +34,17 @@ and this to your crate root:
 You can start using the `fatfs` library now:
 
     let img_file = File::open("fat.img")?;
-    let buf_stream = fatfs::BufStream::new(img_file);
+    let fs = fatfs::FileSystem::new(img_file, fatfs::FsOptions::new())?;
-    let fs = fatfs::FileSystem::new(buf_stream, fatfs::FsOptions::new())?;
     let root_dir = fs.root_dir();
     let mut file = root_dir.create_file("hello.txt")?;
     file.write_all(b"Hello World!")?;
 
+Note: it is recommended to wrap the underlying file struct in a buffering/caching object like `BufStream` from `fscommon` crate. For example:
+
+    extern crate fscommon;
+    let buf_stream = BufStream::new(img_file);
+    let fs = fatfs::FileSystem::new(img_file, fatfs::FsOptions::new())?;
+
 See more examples in the `examples` subdirectory.
 
 no_std usage

src/dir.rs

@@ -94,6 +94,9 @@ enum DirEntryOrShortName<'a, T: ReadWriteSeek + 'a> {
 }
 
 /// A FAT filesystem directory.
+///
+/// This struct is created by the `open_dir` or `create_dir` methods on `Dir`.
+/// The root directory is returned by the `root_dir` method on `FileSystem`.
 pub struct Dir<'a, T: ReadWriteSeek + 'a> {
     stream: DirRawStream<'a, T>,
     fs: &'a FileSystem<T>,
@@ -443,7 +446,9 @@ impl <'a, T: ReadWriteSeek> Clone for Dir<'a, T> {
     }
 }
 
-/// Directory entries iterator.
+/// An iterator over the directory entries.
+///
+/// This struct is created by the `iter` method on `Dir`.
 pub struct DirIter<'a, T: ReadWriteSeek + 'a> {
     stream: DirRawStream<'a, T>,
     fs: &'a FileSystem<T>,

src/dir_entry.rs

@@ -20,7 +20,7 @@ use file::File;
 use dir::{Dir, DirRawStream};
 
 bitflags! {
-    /// FAT file attributes
+    /// A FAT file attributes.
     #[derive(Default)]
     pub struct FileAttributes: u8 {
         const READ_ONLY  = 0x01;
@@ -443,16 +443,20 @@ impl DirEntryData {
     }
 }
 
-/// DOS compatible date
+/// A DOS compatible date.
+///
+/// Used by `DirEntry` time-related methods.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub struct Date {
+    /// Full year - [1980, 2107]
     pub year: u16,
+    /// Month of the year - [1, 12]
     pub month: u16,
+    /// Day of the month - [1, 31]
     pub day: u16,
 }
 
 impl Date {
-
     pub(crate) fn from_u16(dos_date: u16) -> Self {
         let (year, month, day) = ((dos_date >> 9) + 1980, (dos_date >> 5) & 0xF, dos_date & 0x1F);
         Date { year, month, day }
@@ -463,11 +467,18 @@ impl Date {
     }
 }
 
-/// DOS compatible time
+/// A DOS compatible time.
+///
+/// Used by `DirEntry` time-related methods.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub struct Time {
+    /// Hours after midnight - [0, 23]
     pub hour: u16,
+    /// Minutes after the hour - [0, 59]
     pub min: u16,
+    /// Seconds after the minute - [0, 59]
+    ///
+    /// Note: FAT filesystem has a resolution of 2 seconds.
     pub sec: u16,
 }
 
@@ -482,10 +493,14 @@ impl Time {
     }
 }
 
-/// DOS compatible date and time
+/// A DOS compatible date and time.
+///
+/// Used by `DirEntry` time-related methods.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub struct DateTime {
+    /// A date part
     pub date: Date,
+    // A time part
     pub time: Time,
 }
 
@@ -619,7 +634,7 @@ impl DirEntryEditor {
     }
 }
 
-/// FAT directory entry.
+/// A FAT directory entry.
 ///
 /// `DirEntry` is returned by `DirIter` when reading a directory.
 #[derive(Clone)]

src/file.rs

@@ -10,6 +10,8 @@ use dir_entry::{DirEntryEditor, DateTime, Date};
 const MAX_FILE_SIZE: u32 = core::u32::MAX;
 
 /// A FAT filesystem file object used for reading and writing data.
+///
+/// This struct is created by the `open_file` or `create_file` methods on `Dir`.
 pub struct File<'a, T: ReadWriteSeek + 'a> {
     // Note first_cluster is None if file is empty
     first_cluster: Option<u32>,

src/fs.rs

@@ -20,9 +20,9 @@ use alloc::String;
 //   http://wiki.osdev.org/FAT
 //   https://www.win.tue.nl/~aeb/linux/fs/fat/fat-1.html
 
-/// Type of FAT filesystem.
+/// A type of FAT filesystem.
 ///
-/// `FatType` values are based on size of File Allocation Table entry.
+/// `FatType` values are based on the size of File Allocation Table entry.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum FatType {
     Fat12, Fat16, Fat32,
@@ -40,7 +40,7 @@ impl FatType {
     }
 }
 
-/// FAT volume status flags retrived from Boot Sector and allocation table.
+/// A FAT volume status flags retrived from the Boot Sector and the allocation table second entry.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub struct FsStatusFlags {
     pub(crate) dirty: bool,
@@ -48,24 +48,24 @@ pub struct FsStatusFlags {
 }
 
 impl FsStatusFlags {
-    /// Checks if volume is marked as dirty.
+    /// Checks if the volume is marked as dirty.
     ///
     /// Dirty flag means volume has been suddenly ejected from filesystem without unmounting.
     pub fn dirty(&self) -> bool {
         self.dirty
     }
 
-    /// Checks if volume has IO Error flag active.
+    /// Checks if the volume has the IO Error flag active.
     pub fn io_error(&self) -> bool {
         self.io_error
     }
 }
 
-/// Sum of `Read` and `Seek` traits.
+/// A sum of `Read` and `Seek` traits.
 pub trait ReadSeek: Read + Seek {}
 impl<T> ReadSeek for T where T: Read + Seek {}
 
-/// Sum of `Read`, `Write` and `Seek` traits.
+/// A sum of `Read`, `Write` and `Seek` traits.
 pub trait ReadWriteSeek: Read + Write + Seek {}
 impl<T> ReadWriteSeek for T where T: Read + Write + Seek {}
 
@@ -290,28 +290,30 @@ impl FsInfoSector {
     }
 }
 
-/// FAT filesystem mount options.
+/// A FAT filesystem mount options.
+///
+/// Options are specified as an argument for `FileSystem::new` method.
 #[derive(Copy, Clone, Debug)]
 pub struct FsOptions {
     pub(crate) update_accessed_date: bool,
 }
 
 impl FsOptions {
-    /// Creates `FsOptions` struct with default options.
+    /// Creates a `FsOptions` struct with default options.
     pub fn new() -> Self {
         FsOptions {
             update_accessed_date: false,
         }
     }
 
-    /// If enabled library updates accessed date field in directory entry when reading a file.
+    /// If enabled accessed date field in directory entry is updated when reading or writing a file.
     pub fn update_accessed_date(mut self, enabled: bool) -> Self {
         self.update_accessed_date = enabled;
         self
     }
 }
 
-/// FAT volume statistics.
+/// A FAT volume statistics.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub struct FileSystemStats {
     cluster_size: u32,
@@ -336,7 +338,7 @@ impl FileSystemStats {
     }
 }
 
-/// FAT filesystem struct.
+/// A FAT filesystem object.
 ///
 /// `FileSystem` struct is representing a state of a mounted FAT volume.
 pub struct FileSystem<T: ReadWriteSeek> {

src/lib.rs

@@ -1,3 +1,47 @@
+//! A FAT filesystem library implemented in Rust.
+//!
+//! # Usage
+//!
+//! This crate is [on crates.io](https://crates.io/crates/fatfs) and can be
+//! used by adding `fatfs` to the dependencies in your project's `Cargo.toml`.
+//!
+//! ```toml
+//! [dependencies]
+//! fatfs = "0.3"
+//! ```
+//!
+//! And this in your crate root:
+//!
+//! ```rust
+//! extern crate fatfs;
+//! ```
+//!
+//! # Examples
+//!
+//! Initialize a filesystem object (note: `fscommon` crate is used to speedup IO operations):
+//! ```rust
+//! let img_file = File::open("fat.img")?;
+//! let buf_stream = fscommon::BufStream::new(img_file);
+//! let fs = fatfs::FileSystem::new(buf_stream, fatfs::FsOptions::new())?;
+//! ```
+//! Write a file:
+//! ```rust
+//! let root_dir = fs.root_dir();
+//! root_dir.create_dir("foo/bar")?;
+//! let mut file = root_dir.create_file("foo/bar/hello.txt")?;
+//! file.truncate()?;
+//! file.write_all(b"Hello World!")?;
+//! ```
+//! Read a directory:
+//! ```rust
+//! let root_dir = fs.root_dir();
+//! let dir = root_dir.open_dir("foo/bar")?;
+//! for r in dir.iter()? {
+//!     let entry = r?;
+//!     println!(entry.file_name());
+//! }
+//! ```
+
 #![crate_type = "lib"]
 #![crate_name = "fatfs"]