From 04887faaeae7eb0486a178aab0c5e926999f41aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Harabie=C5=84?= Date: Wed, 20 Jun 2018 19:08:50 +0200 Subject: [PATCH] Improve docs --- README.md | 9 +++++++-- src/dir.rs | 7 ++++++- src/dir_entry.rs | 27 +++++++++++++++++++++------ src/file.rs | 2 ++ src/fs.rs | 26 ++++++++++++++------------ src/lib.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 94 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 0bf00da..16f3fa0 100644 --- a/README.md +++ b/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(buf_stream, fatfs::FsOptions::new())?; + let fs = fatfs::FileSystem::new(img_file, 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 diff --git a/src/dir.rs b/src/dir.rs index 251560a..0808585 100644 --- a/src/dir.rs +++ b/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, @@ -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, diff --git a/src/dir_entry.rs b/src/dir_entry.rs index 63b5aff..4895fc6 100644 --- a/src/dir_entry.rs +++ b/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)] diff --git a/src/file.rs b/src/file.rs index 2f1c4b9..7974ff7 100644 --- a/src/file.rs +++ b/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, diff --git a/src/fs.rs b/src/fs.rs index a20a0bb..fdde274 100644 --- a/src/fs.rs +++ b/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 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 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 { diff --git a/src/lib.rs b/src/lib.rs index c0c6137..cc0ffcf 100644 --- a/src/lib.rs +++ b/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"]