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:
parent
ee683e12a3
commit
68cdc8b6d0
@ -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),
|
||||
|
@ -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
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
@ -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, "<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<char> = input.chars().collect();
|
||||
|
@ -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)
|
||||
|
@ -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;
|
||||
|
@ -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,
|
||||
|
@ -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>),
|
||||
|
Loading…
Reference in New Issue
Block a user