Improved crow/mustache.h file documentation (#817)

include/crow/mustache.h

@@ -1,3 +1,9 @@
+/**
+ * \file crow/mustache.h
+ * \brief This file includes the definition of the crow::mustache
+ * namespace and its members.
+ */
+
 #pragma once
 #include <string>
 #include <vector>
@@ -9,14 +15,39 @@
 #include "crow/returnable.h"
 #include "crow/utility.h"
 
-namespace crow
+namespace crow // NOTE: Already documented in "crow/app.h"
 {
+    /**
+     * \namespace crow::mustache
+     * \brief In this namespace is defined most of the functions and
+     * classes related to template rendering.
+     *
+     * If you are here you might want to read these functions and
+     * classes:
+     *
+     * - \ref template_t
+     * - \ref load_text
+     * - \ref load_text_unsafe
+     * - \ref load
+     * - \ref load_unsafe
+     *
+     * As name suggest, crow uses [mustache](https://en.wikipedia.org/wiki/Mustache_(template_system))
+     * as main template rendering system.
+     * 
+     * You may be interested in taking a look at the [Templating guide
+     * page](https://crowcpp.org/master/guides/templating/).
+     */
     namespace mustache
     {
         using context = json::wvalue;
 
         template_t load(const std::string& filename);
 
+        /**
+         * \class invalid_template_exception
+         * \brief Represents compilation error of an template. Throwed
+         * specially at mustache compile time.
+         */
         class invalid_template_exception : public std::exception
         {
         public:
@@ -30,6 +61,15 @@ namespace crow
             std::string msg;
         };
 
+        /**
+         * \struct rendered_template
+         * \brief Returned object after call the
+         * \ref template_t::render() method. Its intended to be
+         * returned during a **rule declaration**.
+         *
+         * \see \ref CROW_ROUTE
+         * \see \ref CROW_BP_ROUTE
+         */
         struct rendered_template : returnable
         {
             rendered_template():
@@ -46,6 +86,13 @@ namespace crow
             }
         };
 
+        /**
+         * \enum ActionType
+         * \brief Used in \ref Action to represent different parsing
+         * behaviors.
+         * 
+         * \see \ref Action
+         */
         enum class ActionType
         {
             Ignore,
@@ -57,6 +104,14 @@ namespace crow
             Partial,
         };
 
+        /**
+         * \struct Action
+         * \brief Used during mustache template compilation to
+         * represent parsing actions.
+         * 
+         * \see \ref compile
+         * \see \ref template_t
+         */
         struct Action
         {
             int start;
@@ -69,7 +124,12 @@ namespace crow
             }
         };
 
-        /// A mustache template object.
+        /**
+         * \class template_t
+         * \brief Compiled mustache template object.
+         *
+         * \warning Use \ref compile instead.
+         */
         class template_t
         {
         public:
@@ -626,10 +686,13 @@ namespace crow
             std::string body_;
         };
 
+        /// \brief The function that compiles a source into a mustache
+        /// template.
         inline template_t compile(const std::string& body)
         {
             return template_t(body);
         }
+
         namespace detail
         {
             inline std::string& get_template_base_directory_ref()
@@ -646,6 +709,9 @@ namespace crow
             }
         } // namespace detail
 
+        /// \brief The default way that \ref load, \ref load_unsafe,
+        /// \ref load_text and \ref load_text_unsafe use to read the
+        /// contents of a file.
         inline std::string default_loader(const std::string& filename)
         {
             std::string path = detail::get_template_base_directory_ref();
@@ -667,6 +733,8 @@ namespace crow
             }
         } // namespace detail
 
+        /// \brief Defines the templates directory path at **route
+        /// level**. By default is `templates/`.
         inline void set_base(const std::string& path)
         {
             auto& base = detail::get_template_base_directory_ref();
@@ -678,6 +746,8 @@ namespace crow
             }
         }
 
+        /// \brief Defines the templates directory path at **global
+        /// level**. By default is `templates/`.
         inline void set_global_base(const std::string& path)
         {
             auto& base = detail::get_global_template_base_directory_ref();
@@ -689,30 +759,70 @@ namespace crow
             }
         }
 
+        /// \brief Change the way that \ref load, \ref load_unsafe,
+        /// \ref load_text and \ref load_text_unsafe reads a file.
+        ///
+        /// By default, the previously mentioned functions load files
+        /// using \ref default_loader, that only reads a file and
+        /// returns a std::string.
         inline void set_loader(std::function<std::string(std::string)> loader)
         {
             detail::get_loader_ref() = std::move(loader);
         }
 
+        /// \brief Open, read and sanitize a file but returns a
+        /// std::string without a previous rendering process.
+        ///
+        /// Except for the **sanitize process** this function does the
+        /// almost the same thing that \ref load_text_unsafe.
         inline std::string load_text(const std::string& filename)
         {
             std::string filename_sanitized(filename);
             utility::sanitize_filename(filename_sanitized);
             return detail::get_loader_ref()(filename_sanitized);
         }
 
+        /// \brief Open and read a file but returns a std::string
+        /// without a previous rendering process.
+        ///
+        /// This function is more like a helper to reduce code like
+        /// this...
+        ///
+        /// ```cpp
+        /// std::ifstream file("home.html");
+        /// return std::string({std::istreambuf_iterator<char>(file), std::istreambuf_iterator<char>()});
+        /// ```
+        ///
+        /// ... Into this...
+        ///
+        /// ```cpp
+        /// return load("home.html");
+        /// ```
+        ///
+        /// \warning Usually \ref load_text is more recommended to use
+        /// instead because it may prevent some [XSS Attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
+        /// **Never blindly trust your users!**
         inline std::string load_text_unsafe(const std::string& filename)
         {
             return detail::get_loader_ref()(filename);
         }
 
+        /// \brief Open, read and renders a file using a mustache
+        /// compiler. It also sanitize the input before compilation.
         inline template_t load(const std::string& filename)
         {
             std::string filename_sanitized(filename);
             utility::sanitize_filename(filename_sanitized);
             return compile(detail::get_loader_ref()(filename_sanitized));
         }
 
+        /// \brief Open, read and renders a file using a mustache
+        /// compiler. But it **do not** sanitize the input before
+        /// compilation.
+        ///
+        /// \warning Usually \ref load is more recommended to use
+        /// instead because it may prevent some [XSS Attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
+        /// **Never blindly trust your users!**
         inline template_t load_unsafe(const std::string& filename)
         {
             return compile(detail::get_loader_ref()(filename));