Add minimal documents for sailfish

sailfish/src/lib.rs

@@ -2,11 +2,12 @@ pub mod runtime;
 
 pub use runtime::{RenderError, RenderResult};
 
+/// Template that can be rendered with consuming itself.
 pub trait TemplateOnce {
     fn render_once(self) -> runtime::RenderResult;
 }
 
 /// WIP
 pub trait Template {
-    fn render(self) -> runtime::RenderResult;
+    fn render(&self) -> runtime::RenderResult;
 }

sailfish/src/runtime/buffer.rs

@@ -1,6 +1,10 @@
 use std::fmt;
 use std::ops::{Add, AddAssign};
 
+/// Buffer for rendered contents
+///
+/// This struct is quite simular to `String`, but some methods are
+/// re-implemented for faster buffering.
 #[derive(Clone, Debug)]
 pub struct Buffer {
     inner: String,

sailfish/src/runtime/escape/mod.rs

@@ -1,3 +1,7 @@
+//! HTML escaping
+//!
+//! By default sailfish replaces the characters `&"<>` with the equivalent html.
+
 mod avx2;
 mod fallback;
 mod naive;
@@ -23,6 +27,9 @@ static ESCAPE_LUT: [u8; 256] = [
 const ESCAPED: [&'static str; 4] = ["&quot;", "&amp;", "&lt;", "&gt;"];
 const ESCAPED_LEN: usize = 4;
 
+/// write the escaped contents with custom function
+///
+/// This function is soft-deprecated because using this function causes a large binary size.
 #[inline]
 pub fn escape_with<F: FnMut(&str)>(mut writer: F, feed: &str) {
     unsafe {
@@ -49,6 +56,17 @@ pub fn escape_to_buf(feed: &str, buf: &mut Buffer) {
     escape_with(|e| buf.write_str(e), feed);
 }
 
+/// write the escaped contents into `String`
+///
+/// # Examples
+///
+/// ```
+/// use sailfish::runtime::escape::escape_to_string;
+///
+/// let mut buf = String::new();
+/// escape_to_string("<h1>Hello, world!</h1>", &mut buf);
+/// assert_eq!(buf, "&lt;h1&gt;Hello, world!&lt;/h1&gt;");
+/// ```
 #[inline]
 pub fn escape_to_string(feed: &str, s: &mut String) {
     unsafe {

sailfish/src/runtime/mod.rs

@@ -1,3 +1,5 @@
+//! Sailfish runtime
+
 mod buffer;
 pub mod escape;
 mod macros;

sailfish/src/runtime/render.rs

@@ -4,6 +4,7 @@ use std::path::{Path, PathBuf};
 use super::buffer::Buffer;
 use super::escape;
 
+/// types which can be rendered inside buffer block (`<%= %>`)
 pub trait Render {
     fn render(&self, b: &mut Buffer) -> fmt::Result;
 

sailfish/src/runtime/size_hint.rs

@@ -1,5 +1,6 @@
 use std::sync::atomic::{AtomicUsize, Ordering};
 
+/// Dynamic size hint
 #[derive(Debug, Default)]
 pub struct SizeHint {
     value: AtomicUsize,