doc: update doc comments

sailfish/src/lib.rs

@@ -44,8 +44,8 @@ pub use runtime::{RenderError, RenderResult};
 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.
+    /// This method never returns `Err`, unless you explicitly return RenderError
+    /// inside templates
     #[inline]
     fn render_once(self) -> runtime::RenderResult {
         let mut buf = String::new();
@@ -54,10 +54,13 @@ pub trait TemplateOnce: Sized {
     }
 
     /// Render the template and append the result to `buf`.
+    ///
+    /// This method never returns `Err`, unless you explicitly return RenderError
+    /// inside templates
     fn render_once_to_string(self, buf: &mut String) -> Result<(), RenderError>;
 }
 
-/// WIP
+/// Work in Progress
 pub trait Template {
     fn render(&self) -> runtime::RenderResult;
 }

sailfish/src/runtime/escape/mod.rs

@@ -1,4 +1,4 @@
-//! HTML escaping
+//! HTML escaping utilities
 //!
 //! By default sailfish replaces the characters `&"'<>` with the equivalent html.
 
@@ -51,11 +51,12 @@ fn escape(feed: &str, buf: &mut Buffer) {
 }
 
 /// Change the default escape function
-#[deprecated(since = "0.1.2", note = "This function does not anything any more")]
+#[doc(hidden)]
 pub fn register_escape_fn(_fun: fn(&str, &mut Buffer)) {}
 
+/// write the escaped contents into `Buffer`
 #[cfg_attr(feature = "perf-inline", inline)]
-pub(crate) fn escape_to_buf(feed: &str, buf: &mut Buffer) {
+pub fn escape_to_buf(feed: &str, buf: &mut Buffer) {
     unsafe {
         if feed.len() < 16 {
             buf.reserve(feed.len() * 6);

sailfish/src/runtime/mod.rs

@@ -32,6 +32,7 @@ pub struct RenderError {
 }
 
 impl RenderError {
+    /// Construct a new error with custom message
     pub fn new(msg: &str) -> Self {
         Self {
             kind: RenderErrorKind::Msg(msg.to_owned()),

sailfish/src/runtime/render.rs

@@ -23,8 +23,10 @@ use super::{escape, RenderError};
 /// }
 /// ```
 pub trait Render {
+    /// render to `Buffer` without escaping
     fn render(&self, b: &mut Buffer) -> Result<(), RenderError>;
 
+    /// render to `Buffer` with HTML escaping
     #[inline]
     fn render_escaped(&self, b: &mut Buffer) -> Result<(), RenderError> {
         let mut tmp = Buffer::new();