Update doc comments

sailfish/src/lib.rs

@@ -42,6 +42,10 @@ pub use runtime::{RenderError, RenderResult};
 
 /// Template that can be rendered with consuming itself.
 pub trait TemplateOnce: Sized {
+    /// Render the template and return the rendering result as `RenderResult`
+    ///
+    /// This method never returns `Err`, unless you manually implement `Render` trait
+    /// for custom type and return `Err` inside it.
     #[inline]
     fn render_once(self) -> runtime::RenderResult {
         let mut buf = String::new();
@@ -49,6 +53,7 @@ pub trait TemplateOnce: Sized {
         Ok(buf)
     }
 
+    /// Render the template and append the result to `buf`.
     fn render_once_to_string(self, buf: &mut String) -> Result<(), RenderError>;
 }
 

sailfish/src/runtime/buffer.rs

@@ -110,6 +110,9 @@ impl Buffer {
         self.len = 0;
     }
 
+    /// Converts a `Buffer` into a `String`.
+    ///
+    /// This consumes the `Buffer`, so we do not need to copy its contents.
     #[inline]
     pub fn into_string(self) -> String {
         let buf = ManuallyDrop::new(self);

sailfish/src/runtime/escape/mod.rs

@@ -38,6 +38,19 @@ pub fn escape(feed: &str, buf: &mut Buffer) {
 }
 
 /// default escape function
+///
+/// This function appends the escaped contents of `feed` into `buf`.
+///
+/// # Examples
+///
+/// ```
+/// use sailfish::runtime::Buffer;
+/// use sailfish::runtime::escape::escape;
+///
+/// let mut buf = Buffer::new();
+/// escape("<h1>Hello, world!</h1>", &mut buf);
+/// assert_eq!(buf.as_str(), "&lt;h1&gt;Hello, world!&lt;/h1&gt;");
+/// ```
 #[cfg(not(target_feature = "avx2"))]
 pub fn escape(feed: &str, buf: &mut Buffer) {
     let fun = if is_x86_feature_detected!("avx2") {
@@ -52,6 +65,7 @@ pub fn escape(feed: &str, buf: &mut Buffer) {
     unsafe { fun(feed, buf) };
 }
 
+/// Change the default escape function
 pub fn register_escape_fn(fun: fn(&str, &mut Buffer)) {
     FN.store(fun as FnRaw, Ordering::Relaxed);
 }

sailfish/src/runtime/render.rs

@@ -4,6 +4,24 @@ use super::buffer::Buffer;
 use super::{escape, RenderError};
 
 /// types which can be rendered inside buffer block (`<%= %>`)
+///
+/// If you want to render the custom data, you must implement this trait and specify
+/// the behaviour.
+///
+/// # Examples
+///
+/// ```
+/// use sailfish::runtime::{Buffer, Render, RenderError};
+///
+/// struct MyU64(u64);
+///
+/// impl Render for MyU64 {
+///     #[inline]
+///     fn render(&self, b: &mut Buffer) -> Result<(), RenderError> {
+///         self.0.render(b)
+///     }
+/// }
+/// ```
 pub trait Render {
     fn render(&self, b: &mut Buffer) -> Result<(), RenderError>;
 

sailfish/src/runtime/size_hint.rs

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