Add basic documentation for visible items

3 files changed, 35 insertions, 2 deletions

diff --git a/askama/src/filters.rs b/askama/src/filters.rs
index a9fe248..3f6aede 100644
--- a/askama/src/filters.rs
+++ b/askama/src/filters.rs
@@ -1,9 +1,14 @@
+//! Module for built-in filter functions
+//!
+//! Contains all the built-in filter functions for use in templates.
+//! Currently, there is no way to define filters outside this module.
 use std::fmt;
 
 fn escapable(b: &u8) -> bool {
     *b == b'<' || *b == b'>' || *b == b'&'
 }
 
+/// Escapes `&`, `<` and `>` in strings
 pub fn escape(s: &fmt::Display) -> String {
     let s = format!("{}", s);
     let mut found = Vec::new();
@@ -39,12 +44,17 @@ pub fn escape(s: &fmt::Display) -> String {
     String::from_utf8(res).unwrap()
 }
 
+/// Alias for the `escape()` filter
 pub fn e(s: &fmt::Display) -> String {
     escape(s)
 }
 
-/// This is actually unused; format filter calls are forwarded directly to
-/// the format!() macro in the code generator (see `visit_filter()`).
+/// Formats arguments according to the specified format
+///
+/// The first argument to this filter must be a string literal (as in normal
+/// Rust). All arguments are passed through to the `format!()`
+/// [macro](https://doc.rust-lang.org/stable/std/macro.format.html) by
+/// the Askama code generator.
 pub fn format() { }
 
 #[cfg(test)]
diff --git a/askama/src/lib.rs b/askama/src/lib.rs
index aa21eed..73313b7 100644
--- a/askama/src/lib.rs
+++ b/askama/src/lib.rs
@@ -2,8 +2,11 @@
 extern crate nom;
 extern crate syn;
 
+/// Main `Template` trait; implementations are generally derived
 pub trait Template {
+    /// Renders the template to the given `writer` buffer
     fn render_to(&self, writer: &mut std::fmt::Write);
+    /// Helper method which allocates a new `String` and renders into it
     fn render(&self) -> String {
         let mut buf = String::new();
         self.render_to(&mut buf);
@@ -18,11 +21,15 @@ mod path;
 pub mod filters;
 pub use path::rerun_if_templates_changed;
 
+// Holds metadata for the template, based on the `template()` attribute.
 struct TemplateMeta {
     path: String,
     print: String,
 }
 
+// Returns a `TemplateMeta` based on the `template()` attribute data found
+// in the parsed struct or enum. Will panic if it does not find the required
+// template path, or if the `print` key has an unexpected value.
 fn get_template_meta(ast: &syn::DeriveInput) -> TemplateMeta {
     let mut path = None;
     let mut print = "none".to_string();
@@ -54,6 +61,13 @@ fn get_template_meta(ast: &syn::DeriveInput) -> TemplateMeta {
     TemplateMeta { path: path.unwrap(), print: print }
 }
 
+/// Takes a `syn::DeriveInput` and generates source code for it
+///
+/// Reads the metadata from the `template()` attribute to get the template
+/// metadata, then fetches the source from the filesystem. The source is
+/// parsed, and the parse tree is fed to the code generator. Will print
+/// the parse tree and/or generated source according to the `print` key's
+/// value as passed to the `template()` attribute.
 pub fn build_template(ast: &syn::DeriveInput) -> String {
     let meta = get_template_meta(ast);
     let src = path::get_template_source(&meta.path);
diff --git a/askama/src/path.rs b/askama/src/path.rs
index 7d75f1b..fb030e5 100644
--- a/askama/src/path.rs
+++ b/askama/src/path.rs
@@ -33,6 +33,15 @@ fn visit_dirs(dir: &Path, cb: &Fn(&DirEntry)) -> io::Result<()> {
     Ok(())
 }
 
+/// Build script helper to rebuild crates if contained templates have changed
+///
+/// Iterates over all files in the template dir (`templates` in
+/// `CARGO_MANIFEST_DIR`) and writes a `cargo:rerun-if-changed=` line for each
+/// of them to stdout.
+///
+/// This helper method can be used in build scripts (`build.rs`) in crates
+/// that have templates, to make sure the crate gets rebuilt when template
+/// source code changes.
 pub fn rerun_if_templates_changed() {
     visit_dirs(&template_dir(), &|e: &DirEntry| {
         println!("cargo:rerun-if-changed={}", e.path().to_str().unwrap());