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 {
|
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),
|
||||||
|
@ -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
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@ -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, "<foo> & <bar>");
|
||||||
|
/// ```
|
||||||
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();
|
||||||
|
@ -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)
|
||||||
|
@ -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;
|
||||||
|
@ -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,
|
||||||
|
@ -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>),
|
||||||
|
Loading…
Reference in New Issue
Block a user