Comment template code

1 files changed, 122 insertions, 28 deletions

diff --git a/lib/template/index.js b/lib/template/index.js
index c9ca66f..3177ae0 100644
--- a/lib/template/index.js
+++ b/lib/template/index.js
@@ -81,8 +81,13 @@ function TemplateEngine(output) {
     error.deprecateField(this.ctx, 'generator', this.output.name, '"generator" property is deprecated, use "output.generator" instead');
 }
 
-// Bind a function to a context
-// Filters and blocks are binded to this context
+/*
+    Bind a function to a context
+    Filters and blocks are binded to this context.
+
+    @param {Function}
+    @param {Function}
+*/
 TemplateEngine.prototype.bindContext = function(func) {
     var that = this;
 
@@ -95,7 +100,13 @@ TemplateEngine.prototype.bindContext = function(func) {
     };
 };
 
-// Interpolate a string content to replace shortcuts according to the filetype
+/*
+    Interpolate a string content to replace shortcuts according to the filetype.
+
+    @param {String} filepath
+    @param {String} source
+    @param {String}
+*/
 TemplateEngine.prototype.interpolate = function(filepath, source) {
     var parser = parsers.getByExt(path.extname(filepath));
     var type = parser? parser.name : null;
@@ -103,7 +114,12 @@ TemplateEngine.prototype.interpolate = function(filepath, source) {
     return this.applyShortcuts(type, source);
 };
 
-// Add a new custom filter
+/*
+    Add a new custom filter, it bind to the right context
+
+    @param {String}
+    @param {Function}
+*/
 TemplateEngine.prototype.addFilter = function(filterName, func) {
     try {
         this.env.getFilter(filterName);
@@ -128,19 +144,31 @@ TemplateEngine.prototype.addFilter = function(filterName, func) {
     return true;
 };
 
-// Add multiple filters at once
+/*
+    Add multiple filters at once
+
+    @param {Map<String:Function>}
+*/
 TemplateEngine.prototype.addFilters = function(filters) {
     _.each(filters, function(filter, name) {
         this.addFilter(name, filter);
     }, this);
 };
 
-// Return true if a block is defined
+/*
+    Return true if a block is defined
+
+    @param {String}
+*/
 TemplateEngine.prototype.hasBlock = function(name) {
     return this.env.hasExtension(blockExtName(name));
 };
 
-// Remove/Disable a block
+/*
+    Remove/Disable a block
+
+    @param {String}
+*/
 TemplateEngine.prototype.removeBlock = function(name) {
     if (!this.hasBlock(name)) return;
 
@@ -153,8 +181,17 @@ TemplateEngine.prototype.removeBlock = function(name) {
     });
 };
 
-// Add a block
-// Using the extensions of nunjucks: https://mozilla.github.io/nunjucks/api.html#addextension
+/*
+    Add a block.
+    Using the extensions of nunjucks: https://mozilla.github.io/nunjucks/api.html#addextension
+
+    @param {String} name
+    @param {BlockDescriptor|Function} block
+    @param {Function} block.process: function to be called to render the block
+    @param {String} block.end: name of the end tag of this block (default to "end<name>")
+    @param {Array<String>} block.blocks: list of inner blocks to parse
+    @param {Array<Shortcut>} block.shortcuts: list of shortcuts to parse this block
+*/
 TemplateEngine.prototype.addBlock = function(name, block) {
     var that = this, Ext, extName;
 
@@ -312,15 +349,27 @@ TemplateEngine.prototype.addBlock = function(name, block) {
     }, this);
 };
 
-// Add multiple blocks at once
+/*
+    Add multiple blocks at once
+
+    @param {Array<BlockDescriptor>}
+*/
 TemplateEngine.prototype.addBlocks = function(blocks) {
     _.each(blocks, function(block, name) {
         this.addBlock(name, block);
     }, this);
 };
 
-// Apply a block to some content
-// This method result depends on the type of block (async or sync)
+/*
+    Apply a block to some content
+    This method result depends on the type of block (async or sync)
+
+
+    @param {String} name: name of the block type to apply
+    @param {Block} blk: content of the block
+    @param {Object} ctx: context of execution of the block
+    @return {Block|Promise<Block>}
+*/
 TemplateEngine.prototype.applyBlock = function(name, blk, ctx) {
     var func, block, r;
 
@@ -346,7 +395,13 @@ TemplateEngine.prototype.applyBlock = function(name, blk, ctx) {
     else return normBlockResult(r);
 };
 
-// Process the result of block in a context
+/*
+    Process the result of block in a context. It returns the content to append to the output.
+    It can return an "anchor" that will be replaced by "replaceBlocks" in "postProcess"
+
+    @param {Block}
+    @return {String}
+*/
 TemplateEngine.prototype.processBlock = function(blk) {
     blk = _.defaults(blk, {
         parse: false,
@@ -368,7 +423,15 @@ TemplateEngine.prototype.processBlock = function(blk) {
     return '{{-%'+blk.id+'%-}}';
 };
 
-// Render a string (without post processing)
+/*
+    Render a string (without post processing)
+
+    @param {String} content: template's content to render
+    @param {Object} context
+    @param {Object} options
+    @param {String} options.path: pathname to the template
+    @return {Promise<String>}
+*/
 TemplateEngine.prototype.render = function(content, context, options) {
     options = _.defaults(options || {}, {
         path: null
@@ -391,13 +454,26 @@ TemplateEngine.prototype.render = function(content, context, options) {
     });
 };
 
-// Render a string with post-processing
+/*
+    Render a string (with post processing)
+
+    @param {String} content: template's content to render
+    @param {Object} context
+    @param {Object} options
+    @return {Promise<String>}
+*/
 TemplateEngine.prototype.renderString = function(content, context, options) {
     return this.render(content, context, options)
     .then(this.postProcess);
 };
 
-// Apply a shortcut to a string
+/*
+    Apply a shortcut of block to a template
+
+    @param {String} content
+    @param {Shortcut} shortcut
+    @return {String}
+*/
 TemplateEngine.prototype.applyShortcut = function(content, shortcut) {
     var regex = new RegExp(
         escapeStringRegexp(shortcut.start) + '([\\s\\S]*?[^\\$])' + escapeStringRegexp(shortcut.end),
@@ -408,8 +484,30 @@ TemplateEngine.prototype.applyShortcut = function(content, shortcut) {
     });
 };
 
-// Replace position markers of blocks by body after processing
-// This is done to avoid that markdown/asciidoc processer parse the block content
+
+/*
+    Apply all shortcut of blocks to a template
+
+    @param {String} type: type of template ("markdown", "asciidoc")
+    @param {String} content
+    @return {String}
+*/
+TemplateEngine.prototype.applyShortcuts = function(type, content) {
+    return _.chain(this.shortcuts)
+        .filter(function(shortcut) {
+            return _.contains(shortcut.parsers, type);
+        })
+        .reduce(this.applyShortcut, content)
+        .value();
+};
+
+/*
+    Replace position markers of blocks by body after processing
+    This is done to avoid that markdown/asciidoc processer parse the block content
+
+    @param {String} content
+    @return {String}
+*/
 TemplateEngine.prototype.replaceBlocks = function(content) {
     var that = this;
 
@@ -423,18 +521,14 @@ TemplateEngine.prototype.replaceBlocks = function(content) {
     });
 };
 
-// Apply all shortcuts to a template
-TemplateEngine.prototype.applyShortcuts = function(type, content) {
-    return _.chain(this.shortcuts)
-        .filter(function(shortcut) {
-            return _.contains(shortcut.parsers, type);
-        })
-        .reduce(this.applyShortcut, content)
-        .value();
-};
 
 
-// Post process content
+/*
+    Post process templating result: remplace block's anchors and apply "post"
+
+    @param {String} content
+    @return {Promise<String>}
+*/
 TemplateEngine.prototype.postProcess = function(content) {
     var that = this;