From 68cdc8b6d0638b09e581cc3a063fa5e0821639a2 Mon Sep 17 00:00:00 2001 From: Elisabeth Henry Date: Sun, 18 Sep 2016 15:16:17 +0200 Subject: [PATCH] Improve documentation strings --- src/lib/bookoption.rs | 26 +++++++++++++++---- src/lib/cleaner.rs | 58 ++++++++++++++++++++++++++++++++++++++----- src/lib/escape.rs | 23 +++++++++++++++-- src/lib/html.rs | 4 +-- src/lib/lib.rs | 10 +++++--- src/lib/number.rs | 12 ++++----- src/lib/token.rs | 2 +- 7 files changed, 110 insertions(+), 25 deletions(-) diff --git a/src/lib/bookoption.rs b/src/lib/bookoption.rs index 94f517e..9121ca1 100644 --- a/src/lib/bookoption.rs +++ b/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 { 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 { 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 { match *self { BookOption::Int(i) => Ok(i), diff --git a/src/lib/cleaner.rs b/src/lib/cleaner.rs index 6f0fab8..06ab2ca 100644 --- a/src/lib/cleaner.rs +++ b/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 . +//! 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 } } - diff --git a/src/lib/escape.rs b/src/lib/escape.rs index fdb50ad..70ae8b8 100644 --- a/src/lib/escape.rs +++ b/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 . -/// 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(" & "); +/// assert_eq!(&s, "<foo> & <bar>"); +/// ``` 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 = input.chars().collect(); diff --git a/src/lib/html.rs b/src/lib/html.rs index eae55f4..301139c 100644 --- a/src/lib/html.rs +++ b/src/lib/html.rs @@ -126,7 +126,7 @@ impl<'a> HtmlRenderer<'a> { Ok(res) } - /// Renders a title (without

tags), increasing header number beforehand + /// Renders a title (without `

` tags), increasing header number beforehand pub fn render_title(&mut self, n: i32, vec: &[Token]) -> Result { 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

tags and appropriate links + /// Renders a title, including `

` tags and appropriate links pub fn render_title_full(&mut self, n: i32, inner: String) -> String { if n == 1 && self.current_hide { format!("

", self.link_number) diff --git a/src/lib/lib.rs b/src/lib/lib.rs index 7f2cc23..f8217cc 100644 --- a/src/lib/lib.rs +++ b/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; diff --git a/src/lib/number.rs b/src/lib/number.rs index 2d8928b..989a9e6 100644 --- a/src/lib/number.rs +++ b/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, diff --git a/src/lib/token.rs b/src/lib/token.rs index ea189b4..7733f68 100644 --- a/src/lib/token.rs +++ b/src/lib/token.rs @@ -32,7 +32,7 @@ pub enum Token { Strong(Vec), /// `Code`, a.k.a. verbatim Code(Vec), - /// > A quote + /// A quote BlockQuote(Vec), /// Code block with language and content CodeBlock(String, Vec),