Doc fix, closes #64

lib/index.js

@@ -381,10 +381,10 @@ MarkdownIt.prototype.use = function (plugin /*, params, ... */) {
  * method directly, until you write custom renderer (for example, to produce
  * AST).
  *
- * `env` is used to pass data between "distributed" rules (`{}` by default).
- * For example, references are parsed in different chains, and need sandbox
- * to store intermediate results. Can be used to inject data in specific cases.
- * You will not need it with high probability.
+ * `env` is used to pass data between "distributed" rules and return additional
+ * metadata like reference info, needed for for renderer. It also can be used to
+ * inject data in specific cases. Usually, you will be ok to pass `{}`,
+ * and then pass updated object to renderer.
  **/
 MarkdownIt.prototype.parse = function (src, env) {
   var state = new this.core.State(src, this, env);
@@ -419,8 +419,8 @@ MarkdownIt.prototype.render = function (src, env) {
  * - env (Object): environment sandbox
  *
  * 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.
+ * block tokens list with the single `inline` element, containing parsed inline
+ * tokens in `children` property. Also updates `env` object.
  **/
 MarkdownIt.prototype.parseInline = function (src, env) {
   var state = new this.core.State(src, this, env);