Improve documentation strings

src/lib/bookoption.rs

@@ -5,12 +5,16 @@ use error::{Error,Result, Source};
 pub enum BookOption {
     /// Stores a String
     String(String),
+
     /// Stores a boolean
     Bool(bool),
+
     /// Stores a single char
     Char(char),
+
     /// Stores an int
     Int(i32),
+    
     /// Stores a path
     ///
     /// Stored the same way as a string, but some base path is usually prepended to it
@@ -18,7 +22,19 @@ pub enum BookOption {
 }
 
 impl BookOption {
-    /// Retuns the BookOption as a &str
+    /// Returns the BookOption as a &str, or an error if it isn't a `String` variant
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use crowbook::BookOption;
+    ///
+    /// let option = BookOption::String("foo".to_owned());
+    /// assert_eq!(option.as_str(), Ok("foo"));
+    ///
+    /// let option = BookOption::Int(42);
+    /// assert!(option.as_str().is_err());
+    /// ```
     pub fn as_str(&self) -> Result<&str> {
         match *self {
             BookOption::String(ref s) => Ok(s),
@@ -27,7 +43,7 @@ impl BookOption {
         }
     }
 
-    /// Returns the BookOption as a &str, but only if it is a path
+    /// Returns the BookOption as a &str, on an error if it isn't a `Path` variant.
     pub fn as_path(&self) -> Result<&str> {
         match *self {
             BookOption::Path(ref s) => Ok(s),
@@ -36,7 +52,7 @@ impl BookOption {
         }
     }
 
-    /// Retuns the BookOption as a bool
+    /// Retuns the BookOption as a bool, or an error if it isn't a `Bool` variant.
     pub fn as_bool(&self) -> Result<bool> {
         match *self {
             BookOption::Bool(b) => Ok(b),
@@ -45,7 +61,7 @@ impl BookOption {
         }
     }
 
-    /// Retuns the BookOption as a char
+    /// Returns the BookOption as a char, or an error if it isn't a `Char` variant.
     pub fn as_char(&self) -> Result<char> {
         match *self {
             BookOption::Char(c) => Ok(c),
@@ -54,7 +70,7 @@ impl BookOption {
         }
     }
     
-    /// Retuns the BookOption as an i32
+    /// Retuns the BookOption as an i32, or an error if it isn't an `Int` variant.
     pub fn as_i32(&self) -> Result<i32> {
         match *self {
             BookOption::Int(i) => Ok(i),

src/lib/cleaner.rs

@@ -15,26 +15,60 @@
 // You should have received ba copy of the GNU Lesser General Public License
 // along with Crowbook.  If not, see <http://www.gnu.org/licenses/>.
 
+//! This module contains the `Cleaner` traits and various implementations of it.
+
+
 /// Custom function because we don't really want to touch \t or \n
 fn is_whitespace(c: char) -> bool {
     c == ' ' || c == ' ' || c == ' '
 }
 
 /// Trait for cleaning a string.
-/// This trait should be called for text that is e.g. in a paragraph, a title,
+///
+/// This trait must be called for text that is e.g. in a paragraph, a title,
 /// NOT for code blocks, hyperlinks and so on!
 pub trait Cleaner: Sync {
     /// Cleans a string. The default implementation is to remove multiple consecutive whitespaces
-    fn clean(&self, _: &mut String, _: bool) {}
+    ///
+    /// # Argumets
+    ///
+    /// * `str`: the string that must be cleaned
+    /// * `latex`: a bool specifying whether output is Latex code or not
+    fn clean(&self, _str: &mut String, _latex: bool) {}
 }
 
-
+/// Cleaner implementation that does nothing
+///
+/// # Examples
+///
+/// ```
+/// use crowbook::Cleaner;
+/// use crowbook::cleaner::Off;
+/// let off = Off;
+/// let mut s = "  A string   that won't be cleaned ".to_owned();
+/// off.clean(&mut s, false);
+/// assert_eq!(&s, "  A string   that won't be cleaned ");
+/// ```
 pub struct Off;
 impl Cleaner for Off {}
 
+/// Default implementation of cleaner trait.
+///
+/// Only removes unnecessary whitespaces.
+///
+/// # Examples
+///
+/// ```
+/// use crowbook::Cleaner;
+/// use crowbook::cleaner::Default;
+/// let default = Default;
+/// let mut s = "  A  string   with   more   whitespaces  than  needed   ".to_owned();
+/// default.clean(&mut s, false);
+/// assert_eq!(&s, " A string with more whitespaces than needed ");
+/// ```
 pub struct Default;
 impl Cleaner for Default {
-    // Remove unnecessary whitespaces
+    /// Remove unnecessary whitespaces
     fn clean(&self, s: &mut String, _: bool) {
         if s.contains(is_whitespace) { // if not, no need to do anything
             let mut new_s = String::with_capacity(s.len());
@@ -59,10 +93,23 @@ impl Cleaner for Default {
 }
 
 /// Implementation for french 'cleaning'
+///
+/// This implementation replaces spaces before some characters (e.g. `?` or `;` with non-breaking spaces
+///
+/// # Examples
+///
+/// ```
+/// use crowbook::Cleaner;
+/// use crowbook::cleaner::French;
+/// let french = French;
+/// let mut s = "  Bonjour ! Comment allez-vous   ?   ".to_owned();
+/// french.clean(&mut s, true); // clean for latex so we see the non-breaking spaces easily
+/// assert_eq!(&s, " Bonjour~! Comment allez-vous~? ");
+/// ```
 pub struct French;
 
 impl Cleaner for French {
-    // puts non breaking spaces between :, ;, ?, !, «, »
+    /// Puts non breaking spaces before/after `:`, `;`, `?`, `!`, `«`, `»`, `—`
     fn clean(&self, s: &mut String, latex: bool) {
         fn is_trouble(c: char) -> bool {
             match c {
@@ -138,5 +185,4 @@ impl Cleaner for French {
         *s = new_s
     }
 }
-            
 

src/lib/escape.rs

@@ -15,7 +15,18 @@
 // You should have received ba copy of the GNU Lesser General Public License
 // along with Crowbook.  If not, see <http://www.gnu.org/licenses/>.
 
-/// Escape characters <, >, and &
+//! Provides utility functions for escaping text to HTML or LaTeX
+
+
+/// Escape characters `<`, `>`, and `&`
+///
+/// # Examples
+///
+/// ```
+/// use crowbook::escape::escape_html;
+/// let s = escape_html("<foo> & <bar>");
+/// assert_eq!(&s, "&lt;foo&gt; &amp; &lt;bar&gt;");
+/// ```
 pub fn escape_html(input: &str) -> String {
     let mut output = String::new();
     for c in input.chars() {
@@ -30,7 +41,15 @@ pub fn escape_html(input: &str) -> String {
     output
 }
 
-/// Escape characters for tex file
+/// Escape characters for LaTeX
+///
+/// # Examples
+///
+/// ```
+/// use crowbook::escape::escape_tex;
+/// let s = escape_tex("command --foo # calls command with option foo");
+/// assert_eq!(&s, r"command -{}-foo \# calls command with option foo");
+/// ```
 pub fn escape_tex(input: &str) -> String {
     let mut output = String::new();
     let mut chars:Vec<char> = input.chars().collect();

src/lib/html.rs

@@ -126,7 +126,7 @@ impl<'a> HtmlRenderer<'a> {
         Ok(res)
     }
 
-    /// Renders a title (without <h1> tags), increasing header number beforehand
+    /// Renders a title (without `<h1>` tags), increasing header number beforehand
     pub fn render_title(&mut self, n: i32, vec: &[Token]) -> Result<String> {
         self.inc_header(n);
         let s = if n == 1 && self.current_numbering >= 1 {
@@ -140,7 +140,7 @@ impl<'a> HtmlRenderer<'a> {
         Ok(s)
     }
 
-    /// Renders a title, including <h1> tags and appropriate links
+    /// Renders a title, including `<h1>` tags and appropriate links
     pub fn render_title_full(&mut self, n: i32, inner: String) -> String {
         if n == 1 && self.current_hide {
             format!("<h1 id = \"link-{}\"></h1>", self.link_number)

src/lib/lib.rs

@@ -106,6 +106,9 @@ extern crate walkdir;
 extern crate rustc_serialize;
 extern crate crossbeam;
 
+pub mod cleaner;
+pub mod escape;
+
 pub use parser::Parser;
 pub use book::Book;
 pub use bookoption::BookOption;
@@ -116,7 +119,7 @@ pub use latex::LatexRenderer;
 pub use odt::OdtRenderer;
 pub use error::{Result, Error, Source};
 pub use token::Token;
-pub use cleaner::{Cleaner, French};
+pub use cleaner::{Cleaner};
 pub use number::Number;
 pub use resource_handler::ResourceHandler;
 pub use logger::{Logger, InfoLevel};
@@ -124,6 +127,8 @@ pub use html_dir::HtmlDirRenderer;
 pub use html_single::HtmlSingleRenderer;
 pub use renderer::Renderer;
 
+
+
 #[macro_use]
 mod html;
 mod html_dir;
@@ -134,7 +139,7 @@ mod latex;
 mod odt;
 mod parser;
 mod token;
-mod cleaner;
+
 mod number;
 mod resource_handler;
 mod logger;
@@ -143,7 +148,6 @@ mod lang;
 mod renderer;
 mod html_single;
 
-mod escape;
 mod toc;
 mod zipper;
 mod templates;

src/lib/number.rs

@@ -1,24 +1,24 @@
 /// Numbering for a given chapter
 #[derive(Debug, PartialEq, Clone, Copy)]
 pub enum Number {
-    /// chapter's title is hidden
+    /// Chapter's title is hidden
     Hidden,
-    /// chapter is not numbered
+    /// Chapter is not numbered
     Unnumbered,
-    /// chapter follows books numbering, number is given automatically
+    /// Chapter follows books numbering, number is given automatically
     Default,
-    /// chapter number set to specified number
+    /// Chapter number set to specified number
     Specified(i32), 
 }
 
 
 impl Number {
-    /// Returns true if number is hidden
+    /// Returns true if self is hidden
     pub fn is_hidden(&self) -> bool {
         *self == Number::Hidden
     }
 
-    /// Returns true if number is numbered
+    /// Returns true if self is numbered
     pub fn is_numbered(&self) -> bool {
         match *self {
             Number::Hidden | Number::Unnumbered => false,

src/lib/token.rs

@@ -32,7 +32,7 @@ pub enum Token {
     Strong(Vec<Token>),
     /// `Code`, a.k.a. verbatim
     Code(Vec<Token>),
-    /// > A quote
+    /// A quote
     BlockQuote(Vec<Token>),
     /// Code block with language and content
     CodeBlock(String, Vec<Token>),