From 224e0524028e65ff7d5cf53c5b18d1dd407dfd43 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Tue, 17 Oct 2017 21:38:57 -0700 Subject: start working in docs --- src/lib.rs | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'src/lib.rs') diff --git a/src/lib.rs b/src/lib.rs index 12ce2d1..c51ce89 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,7 @@ +//! Is this where crate-level docs go? +//! Yes. + #[macro_use] extern crate error_chain; extern crate integer_encoding; @@ -26,18 +29,36 @@ mod errors { pub use errors::*; -// Abstract access to SLEEP content +/// Abstract access to SLEEP content. +/// Back-ends could be in RAM, on disk, remote HTTP, etc. pub trait SleepStorage { + + /// Returns the 32-bit "magic word", indicating the content type, in native format (aka, not + /// necessarily big-endian). fn get_magic(&self) -> u32; + + /// If the algorithm string is empty, returns None, otherwise the String (owned), decoded from + /// UTF-8. Encoded (bytes) representation is at most 24 bytes. fn get_algorithm(&self) -> Option; + + /// Size (in bytes) of each entry for this SLEEP file. fn get_entry_size(&self) -> u16; + + /// Returns a single raw entry at the given index (which is not a byte offset). + /// TODO: should write into a supplied buffer and return size. fn read(&mut self, index: u64) -> Result>; + + /// Writes an entry at the given entry index (which is not a byte offset). fn write(&mut self, index: u64, data: &[u8]) -> Result<()>; + + /// Returns the count of entries, meaning the highest index entry plus one (not necessarily the + /// number of entries which have actually been written). fn len(&self) -> Result; } #[derive(Debug)] pub struct SleepFile { + /// Local File implementation of SleepStorage file: File, magic: u32, entry_size: u16, -- cgit v1.2.3