Auto merge of #128 - matthiasbeyer:libimagstore/source-doc, r=matthiasbeyer

Libimagstore/source doc

Add documentation to libimagstore types.

libimagstore/src/content.rs

@@ -1 +1,4 @@
+/**
+ * EntryContent type
+ */
 pub type EntryContent = String;

libimagstore/src/entry.rs

@@ -2,6 +2,11 @@ use header::EntryHeader;
 use content::EntryContent;
 use store::StoreId;
 
+/**
+ * An Entry of the store
+ *
+ * Contains location, header and content part.
+ */
 #[derive(Debug, Clone)]
 pub struct Entry {
     location: StoreId,

libimagstore/src/error.rs

@@ -4,6 +4,9 @@ use std::fmt::Formatter;
 use std::fmt::Error as FmtError;
 use std::clone::Clone;
 
+/**
+ * Kind of store error
+ */
 #[derive(Clone, Copy, Debug)]
 pub enum StoreErrorKind {
     FileError,
@@ -35,6 +38,9 @@ impl Display for StoreErrorKind {
 
 }
 
+/**
+ * Store error type
+ */
 #[derive(Debug)]
 pub struct StoreError {
     err_type: StoreErrorKind,
@@ -43,6 +49,9 @@ pub struct StoreError {
 
 impl StoreError {
 
+    /**
+     * Build a new StoreError from an StoreErrorKind, optionally with cause
+     */
     pub fn new(errtype: StoreErrorKind, cause: Option<Box<Error>>)
         -> StoreError
     {
@@ -52,6 +61,9 @@ impl StoreError {
         }
     }
 
+    /**
+     * Get the error type of this StoreError
+     */
     pub fn err_type(&self) -> StoreErrorKind {
         self.err_type.clone()
     }

libimagstore/src/header.rs

@@ -1,5 +1,11 @@
 use toml::Table;
 
+/**
+ * EntryHeader
+ *
+ * This is basically a wrapper around toml::Table which provides convenience to the user of the
+ * librray.
+ */
 #[derive(Debug, Clone)]
 pub struct EntryHeader {
     toml: Table,
@@ -7,12 +13,18 @@ pub struct EntryHeader {
 
 impl EntryHeader {
 
+    /**
+     * Get a new header object with a already-filled toml table
+     */
     pub fn new(toml: Table) -> EntryHeader {
         EntryHeader {
             toml: toml,
         }
     }
 
+    /**
+     * Get the table which lives in the background
+     */
     pub fn toml(&self) -> &Table {
         &self.toml
     }

libimagstore/src/lazyfile.rs

@@ -4,6 +4,11 @@ use std::io::{Seek, SeekFrom};
 use std::path::{Path, PathBuf};
 use std::fs::{File, OpenOptions};
 
+/**
+ * LazyFile type
+ *
+ * A lazy file is either absent, but a path to it is available, or it is present.
+ */
 pub enum LazyFile {
     Absent(PathBuf),
     File(File)
@@ -18,13 +23,24 @@ fn create_file<A: AsRef<Path>>(p: A) -> ::std::io::Result<File> {
 }
 
 impl LazyFile {
+
+    /**
+     * Create a new LazyFile instance from a Path
+     */
     pub fn new(p: PathBuf) -> LazyFile {
         LazyFile::Absent(p)
     }
+
+    /**
+     * Create a new LazyFile instance from an already existing file
+     */
     pub fn new_with_file(f: File) -> LazyFile {
         LazyFile::File(f)
     }
 
+    /**
+     * Get the file behind a LazyFile object
+     */
     pub fn get_file(&mut self) -> Result<&File, StoreError> {
         match self.get_file_mut() {
             Ok(file) => Ok(&*file),
@@ -32,6 +48,9 @@ impl LazyFile {
         }
     }
 
+    /**
+     * Get the mutable file behind a LazyFile object
+     */
     pub fn get_file_mut(&mut self) -> Result<&mut File, StoreError> {
         let file = match *self {
             LazyFile::File(ref mut f) => return {
@@ -56,6 +75,9 @@ impl LazyFile {
         unreachable!()
     }
 
+    /**
+     * Create a file out of this LazyFile object
+     */
     pub fn create_file(&mut self) -> Result<&mut File, StoreError> {
         let file = match *self {
             LazyFile::File(ref mut f) => return Ok(f),