apidoc: docs update + Renderer info

lib/index.js

@@ -360,7 +360,9 @@ MarkdownIt.prototype.render = function (src, env) {
  * - src (String): source string
  * - env (Object): enviroment variables
  *
- * The same as [[MarkdownIt.parse]] but skip all block rules.
+ * The same as [[MarkdownIt.parse]] but skip all block rules. It returns the
+ * block tokens list with th single `inline` element, containing parsed inline
+ * tokens in `children` property.
  **/
 MarkdownIt.prototype.parseInline = function (src, env) {
   var state = new StateCore(this, src, env);

lib/renderer.js

@@ -1,3 +1,10 @@
+/**
+ * class Renderer
+ *
+ * Generates HTML from parsed token stream. Each instance has independent
+ * copy of rules. Those can be rewritten with ease. Also, you can add new
+ * rules if you create plugin and adds new token types.
+ **/
 'use strict';
 
 
@@ -324,13 +331,53 @@ rules.dd_close = function() {
 };
 
 
-// Renderer class
+/**
+ * new Renderer()
+ *
+ * Creates new [[Renderer]] instance and fill [[Renderer#rules]] with defaults.
+ **/
 function Renderer() {
-  // Clone rules object to allow local modifications
+
+  /**
+   * Renderer#rules -> Object
+   *
+   * Contains render rules for tokens. Can be updated and extended.
+   *
+   * ##### Example
+   *
+   * ```javascript
+   * var md = require('markdown-it')();
+   *
+   * md.renderer.rules.strong_open  = function () { return '<b>'; };
+   * md.renderer.rules.strong_close = function () { return '</b>'; };
+   *
+   * var result = md.renderInline(...);
+   * ```
+   *
+   * Each rule is called as independed static function with fixed signature:
+   *
+   * ```javascript
+   * function my_token_render(tokens, idx, options, env, self) {
+   *   // ...
+   *   return renderedHTML;
+   * }
+   * ```
+   *
+   * See [source code](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js)
+   * for more details and examples.
+   **/
   this.rules = assign({}, rules);
 }
 
 
+/**
+ * Renderer.renderInline(tokens, options, env) -> String
+ * - tokens (Array): list on block tokens to renter
+ * - options (Object): params of parser instance
+ * - env (Object): additional data from parsed input (references, for example)
+ *
+ * The same as [[Renderer.render]], but for single token of `inline` type.
+ **/
 Renderer.prototype.renderInline = function (tokens, options, env) {
   var result = '',
       _rules = this.rules;
@@ -343,6 +390,16 @@ Renderer.prototype.renderInline = function (tokens, options, env) {
 };
 
 
+/** internal
+ * Renderer.renderInlineAsText(tokens, options, env) -> String
+ * - tokens (Array): list on block tokens to renter
+ * - options (Object): params of parser instance
+ * - env (Object): additional data from parsed input (references, for example)
+ *
+ * Special kludge for image `alt` attributes to conform CommonMark spec.
+ * Don't try to use it! Spec requires to show `alt` content with stripped markup,
+ * instead of simple escaping.
+ **/
 Renderer.prototype.renderInlineAsText = function (tokens, options, env) {
   var result = '',
       _rules = this.rules;
@@ -359,6 +416,15 @@ Renderer.prototype.renderInlineAsText = function (tokens, options, env) {
 };
 
 
+/**
+ * Renderer.render(tokens, options, env) -> String
+ * - tokens (Array): list on block tokens to renter
+ * - options (Object): params of parser instance
+ * - env (Object): additional data from parsed input (references, for example)
+ *
+ * Takes token stream and generates HTML. Probably, you will never need to call
+ * this method directly.
+ **/
 Renderer.prototype.render = function (tokens, options, env) {
   var i, len,
       result = '',

lib/ruler.js

@@ -1,11 +1,3 @@
-// Ruler is helper class to build responsibility chains from parse rules.
-// It allows:
-//
-// - easy stack rules chains
-// - getting main chain and named chains content (as arrays of functions)
-//
-'use strict';
-
 /**
  * class Ruler
  *
@@ -23,6 +15,7 @@
  * rules control use [[MarkdownIt.disable]], [[MarkdownIt.enable]] and
  * [[MarkdownIt.use]].
  **/
+'use strict';
 
 
 /**

support/api_header.md

@@ -1,5 +1,12 @@
+<!-- styles hack until ndoc updated -->
+<style>
+header .name_prefix { font-weight: normal; }
+</style>
+
 # markdown-it API
 
+### Simple use
+
 In most cases you will use `markdown-it` in very simple way:
 
 ```javascript
@@ -11,7 +18,9 @@ var result = md.render(your_markdown_string);
 var resultInline = md.renderInline(your_markdown_inline_string);
 ```
 
-Advanced usage consist of this steps:
+### Advanced use
+
+Advanced use consist of this steps:
 
 1. Create instance with desired preset & options.
 2. Add plugins.
@@ -19,8 +28,10 @@ Advanced usage consist of this steps:
 4. Rewrite renderer functions.
 5. Use result to call `.render()` or `.renderInline()` method.
 
+Of cause, you can skip not needed steps, or change sequense.
+
 
-Example 1. Minimalistic mode with bold, italic and line breaks:
+__Example 1.__ Minimalistic mode with bold, italic and line breaks:
 
 ```javascript
 var md = require('markdown-it')('zero', { breaks: true })
@@ -29,7 +40,8 @@ var md = require('markdown-it')('zero', { breaks: true })
 var result = md.renderInline(...);
 ```
 
-Example 2. Load plugin and disable tables:
+
+__Example 2.__ Load plugin and disable tables:
 
 ```javascript
 var md = require('markdown-it')()
@@ -39,7 +51,8 @@ var md = require('markdown-it')()
 var result = md.render(...);
 ```
 
-Example 3. Replace `<strong>` with `<b>` in rendered result:
+
+__Example 3.__ Replace `<strong>` with `<b>` in rendered result:
 
 ```javascript
 var md = require('markdown-it')();
@@ -50,4 +63,5 @@ md.renderer.rules.strong_close = function () { return '</b>'; };
 var result = md.renderInline(...);
 ```
 
+
 See classes doc for all available features and more examples.