Core, ParseBlock, ParseInline minimal docs & minor fixes

CHANGELOG.md

@@ -2,6 +2,7 @@
 ------------------
 
 - Updated CM spec conformance to v0.13 (partially).
+- API docs.
 - Added 'zero' preset.
 - Fixed block termination check when rules are disabled.
 

Makefile

@@ -72,7 +72,7 @@ gh-doc: doc
 		&& git commit -m "Auto-generate API doc" \
 		&& git remote add remote git@github.com:markdown-it/markdown-it.git \
 		&& git push --force remote +master:gh-pages
-	rm -rf ./demo
+	rm -rf ./apidoc
 
 publish:
 	@if test 0 -ne `git status --porcelain | wc -l` ; then \
@@ -106,5 +106,5 @@ todo:
 	grep 'TODO' -n -r ./lib 2>/dev/null || test true
 
 
-.PHONY: publish lint test gh-pages todo demo coverage apidoc
+.PHONY: publish lint test gh-pages todo demo coverage doc
 .SILENT: help lint test todo

lib/parser_block.js

@@ -1,6 +1,8 @@
-// Block parser
-
-
+/** internal
+ * class ParserBlock
+ *
+ * Block-level tokenizer.
+ **/
 'use strict';
 
 
@@ -24,9 +26,15 @@ var _rules = [
 ];
 
 
-// Block Parser class
-//
+/**
+ * new ParserBlock()
+ **/
 function ParserBlock() {
+  /**
+   * ParserBlock#ruler -> Ruler
+   *
+   * [[Ruler]] instance. Keep configuration of block rules.
+   **/
   this.ruler = new Ruler();
 
   for (var i = 0; i < _rules.length; i++) {
@@ -91,6 +99,11 @@ var NEWLINES_RE  = /\r[\n\u0085]|[\u2424\u2028\u0085]/g;
 var SPACES_RE    = /\u00a0/g;
 var NULL_RE      = /\u0000/g;
 
+/**
+ * ParserBlock.parse(str, options, env, outTokens)
+ *
+ * Process input string and push block tokens into `outTokens`
+ **/
 ParserBlock.prototype.parse = function (src, options, env, outTokens) {
   var state, lineStart = 0, lastTabPos = 0;
 

lib/parser_core.js

@@ -1,5 +1,9 @@
-// Class of top level (`core`)  rules
-//
+/** internal
+ * class Core
+ *
+ * Top-level rules executor. Glues block/inline parsers and does intermediate
+ * transformations.
+ **/
 'use strict';
 
 
@@ -19,9 +23,15 @@ var _rules = [
 ];
 
 
+/**
+ * new Core()
+ **/
 function Core() {
-  this.options = {};
-
+  /**
+   * Core#ruler -> Ruler
+   *
+   * [[Ruler]] instance. Keep configuration of core rules.
+   **/
   this.ruler = new Ruler();
 
   for (var i = 0; i < _rules.length; i++) {
@@ -30,6 +40,11 @@ function Core() {
 }
 
 
+/**
+ * Core.process(state)
+ *
+ * Executes core chain rules.
+ **/
 Core.prototype.process = function (state) {
   var i, l, rules;
 

lib/parser_inline.js

@@ -1,5 +1,8 @@
-// Inline parser
-
+/** internal
+ * class ParserInline
+ *
+ * Tokenizes paragraph content.
+ **/
 'use strict';
 
 
@@ -44,13 +47,31 @@ function validateLink(url) {
   return true;
 }
 
-// Inline Parser class
-//
+
+/**
+ * new ParserInline()
+ **/
 function ParserInline() {
-  // By default CommonMark allows too much in links
-  // If you need to restrict it - override this with your validator.
+  /**
+   * ParserInline#validateLink(url) -> Boolean
+   *
+   * Link validation function. CommonMark allows too much in links. By default
+   * we disable `javascript:` and `vbscript:` schemas. You can change this
+   * behaviour.
+   *
+   * ```javascript
+   * var md = require('markdown-it')();
+   * // enable everything
+   * md.inline.validateLink = function () { return true; }
+   * ```
+   **/
   this.validateLink = validateLink;
 
+  /**
+   * ParserInline#ruler -> Ruler
+   *
+   * [[Ruler]] instance. Keep configuration of inline rules.
+   **/
   this.ruler = new Ruler();
 
   for (var i = 0; i < _rules.length; i++) {
@@ -120,8 +141,11 @@ ParserInline.prototype.tokenize = function (state) {
 };
 
 
-// Parse input string.
-//
+/**
+ * ParserInline.parse(str, options, env, outTokens)
+ *
+ * Process input string and push inline tokens into `outTokens`
+ **/
 ParserInline.prototype.parse = function (str, options, env, outTokens) {
   var state = new StateInline(str, this, options, env, outTokens);