1
0
mirror of https://github.com/lise-henry/crowbook synced 2024-09-28 02:59:45 +02:00

Improve documentation strings

This commit is contained in:
Elisabeth Henry 2016-09-18 15:16:17 +02:00
parent ee683e12a3
commit 68cdc8b6d0
7 changed files with 110 additions and 25 deletions

View File

@ -5,12 +5,16 @@ use error::{Error,Result, Source};
pub enum BookOption { pub enum BookOption {
/// Stores a String /// Stores a String
String(String), String(String),
/// Stores a boolean /// Stores a boolean
Bool(bool), Bool(bool),
/// Stores a single char /// Stores a single char
Char(char), Char(char),
/// Stores an int /// Stores an int
Int(i32), Int(i32),
/// Stores a path /// Stores a path
/// ///
/// Stored the same way as a string, but some base path is usually prepended to it /// 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 { 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> { pub fn as_str(&self) -> Result<&str> {
match *self { match *self {
BookOption::String(ref s) => Ok(s), 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> { pub fn as_path(&self) -> Result<&str> {
match *self { match *self {
BookOption::Path(ref s) => Ok(s), 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> { pub fn as_bool(&self) -> Result<bool> {
match *self { match *self {
BookOption::Bool(b) => Ok(b), 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> { pub fn as_char(&self) -> Result<char> {
match *self { match *self {
BookOption::Char(c) => Ok(c), 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> { pub fn as_i32(&self) -> Result<i32> {
match *self { match *self {
BookOption::Int(i) => Ok(i), BookOption::Int(i) => Ok(i),

View File

@ -15,26 +15,60 @@
// You should have received ba copy of the GNU Lesser General Public License // You should have received ba copy of the GNU Lesser General Public License
// along with Crowbook. If not, see <http://www.gnu.org/licenses/>. // 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 /// Custom function because we don't really want to touch \t or \n
fn is_whitespace(c: char) -> bool { fn is_whitespace(c: char) -> bool {
c == ' ' || c == ' ' || c == '' c == ' ' || c == ' ' || c == ''
} }
/// Trait for cleaning a string. /// 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! /// NOT for code blocks, hyperlinks and so on!
pub trait Cleaner: Sync { pub trait Cleaner: Sync {
/// Cleans a string. The default implementation is to remove multiple consecutive whitespaces /// 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; pub struct Off;
impl Cleaner for 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; pub struct Default;
impl Cleaner for Default { impl Cleaner for Default {
// Remove unnecessary whitespaces /// Remove unnecessary whitespaces
fn clean(&self, s: &mut String, _: bool) { fn clean(&self, s: &mut String, _: bool) {
if s.contains(is_whitespace) { // if not, no need to do anything if s.contains(is_whitespace) { // if not, no need to do anything
let mut new_s = String::with_capacity(s.len()); let mut new_s = String::with_capacity(s.len());
@ -59,10 +93,23 @@ impl Cleaner for Default {
} }
/// Implementation for french 'cleaning' /// 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; pub struct French;
impl Cleaner for 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 clean(&self, s: &mut String, latex: bool) {
fn is_trouble(c: char) -> bool { fn is_trouble(c: char) -> bool {
match c { match c {
@ -138,5 +185,4 @@ impl Cleaner for French {
*s = new_s *s = new_s
} }
} }

View File

@ -15,7 +15,18 @@
// You should have received ba copy of the GNU Lesser General Public License // You should have received ba copy of the GNU Lesser General Public License
// along with Crowbook. If not, see <http://www.gnu.org/licenses/>. // 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 { pub fn escape_html(input: &str) -> String {
let mut output = String::new(); let mut output = String::new();
for c in input.chars() { for c in input.chars() {
@ -30,7 +41,15 @@ pub fn escape_html(input: &str) -> String {
output 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 { pub fn escape_tex(input: &str) -> String {
let mut output = String::new(); let mut output = String::new();
let mut chars:Vec<char> = input.chars().collect(); let mut chars:Vec<char> = input.chars().collect();

View File

@ -126,7 +126,7 @@ impl<'a> HtmlRenderer<'a> {
Ok(res) 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> { pub fn render_title(&mut self, n: i32, vec: &[Token]) -> Result<String> {
self.inc_header(n); self.inc_header(n);
let s = if n == 1 && self.current_numbering >= 1 { let s = if n == 1 && self.current_numbering >= 1 {
@ -140,7 +140,7 @@ impl<'a> HtmlRenderer<'a> {
Ok(s) 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 { pub fn render_title_full(&mut self, n: i32, inner: String) -> String {
if n == 1 && self.current_hide { if n == 1 && self.current_hide {
format!("<h1 id = \"link-{}\"></h1>", self.link_number) format!("<h1 id = \"link-{}\"></h1>", self.link_number)

View File

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

View File

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

View File

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