Added JSDoc

.jsdoc.json

@@ -0,0 +1,25 @@
+{
+	"plugins": [
+		"plugins/markdown"
+	],
+	"opts": {
+		"destination": "./docs",
+		"template": "./node_modules/minami"
+	},
+	"recurseDepth": 10,
+	"source": {
+		"includePattern": "\\.js$",
+		"excludePattern": "\\.min\\.js$"
+	},
+	"tags": {
+		"allowUnknownTags": true,
+		"dictionaries": [
+			"jsdoc",
+			"closure"
+		]
+	},
+	"templates": {
+		"cleverLinks": true,
+		"monospaceLinks": true
+	}
+}

components/prism-core.doc.js

@@ -0,0 +1,37 @@
+/**
+ * The expansion of a simple `RegExp` literal to support additional properties.
+ *
+ * @typedef TokenObject
+ * @property {RegExp} pattern The regular expression of the token.
+ * @property {boolean} [lookbehind=false] If `true`, then the first capturing group of `pattern` will (effectively)
+ * behave as a lookbehind group meaning that the captured text will not be part of the matched text of the new token.
+ * @property {boolean} [greedy=false] Whether the token is greedy.
+ * @property {string|string[]} [alias] An optional alias or list of aliases.
+ * @property {Grammar} [inside] The nested tokens of this token.
+ *
+ * This can be used for recursive language definitions.
+ *
+ * Note that this can cause infinite recursion.
+*/
+
+/**
+ * @typedef Grammar
+ * @type {Object.<string, RegExp | TokenObject | Array.<RegExp | TokenObject>>}
+ * @property {Grammar} [rest] An optional grammar object that will appended to this grammar.
+ */
+
+/**
+ * A function which will invoked after an element was successfully highlighted.
+ *
+ * @callback HighlightCallback
+ * @param {HTMLElement} element The element successfully highlighted.
+ * @returns {void}
+ * @memberof Prism
+*/
+
+/**
+ * @callback HookCallback
+ * @param {Object.<string, any>} env The environment variables of the hook.
+ * @returns {void}
+ * @memberof Prism.hooks
+ */

components/prism-core.js

@@ -8,8 +8,9 @@ var _self = (typeof window !== 'undefined')
 
 /**
  * Prism: Lightweight, robust, elegant syntax highlighting
- * MIT license http://www.opensource.org/licenses/mit-license.php/
- * @author Lea Verou http://lea.verou.me
+ * @license MIT license http://www.opensource.org/licenses/mit-license.php/
+ * @author Lea Verou <http://lea.verou.me>
+ * @namespace
  */
 
 var Prism = (function (_self){
@@ -85,7 +86,27 @@ var _ = {
 		}
 	},
 
+	/**
+	 * This namespace contains all currently loaded languages and the some helper functions to create and modify languages.
+	 *
+	 * @namespace
+	 * @memberof Prism
+	 */
 	languages: {
+		/**
+		 * Creates a deep copy of the language with the given id and appends the given tokens.
+		 *
+		 * If a token in `redef` also appears in the copied language, then the existing token in the copied language
+		 * will be overwritten at its original position.
+		 *
+		 * @param {string} id The id of the language to extend. This has to be a key in `Prism.languages`.
+		 * @param {Grammar} redef The new tokens to append.
+		 * @returns {Grammar} The new language created.
+		 * @example
+		 * Prism.languages['css-with-colors'] = Prism.languages.extend('css', {
+		 *     'color': /\b(?:red|green|blue)\b/
+		 * });
+		 */
 		extend: function (id, redef) {
 			var lang = _.util.clone(_.languages[id]);
 
@@ -97,13 +118,28 @@ var _ = {
 		},
 
 		/**
-		 * Insert a token before another token in a language literal
+		 * Inserts tokens _before_ another token in a language definition or any other grammar.
+		 *
 		 * As this needs to recreate the object (we cannot actually insert before keys in object literals),
 		 * we cannot just provide an object, we need an object and a key.
-		 * @param inside The key (or language id) of the parent
-		 * @param before The key to insert before.
-		 * @param insert Object with the key/value pairs to insert
-		 * @param root The object that contains `inside`. If equal to Prism.languages, it can be omitted.
+		 *
+		 * If the grammar of `inside` and `insert` have tokens with the same name, the tokens in `inside` will be ignored.
+		 *
+		 * All references of the old object accessible from `Prism.languages` or `insert` will be replace with the new one.
+		 *
+		 * @param {string} inside The property of `root` that contains the object to be modified.
+		 *
+		 * This is usually a language id.
+		 * @param {string} before The key to insert before.
+		 * @param {Grammar} insert An object containing the key-value pairs to be inserted.
+		 * @param {Object.<string, Grammar>} [root] The object containing `inside`, i.e. the object that contains the object that will be modified.
+		 *
+		 * Defaults to `Prism.languages`.
+		 * @returns {Grammar} The new grammar created.
+		 * @example
+		 * Prism.languages.insertBefore('markup', 'cdata', {
+		 *     'style': { ... }
+		 * });
 		 */
 		insertBefore: function (inside, before, insert, root) {
 			root = root || _.languages;
@@ -168,10 +204,35 @@ var _ = {
 	},
 	plugins: {},
 
+	/**
+	 * This is the most high-level function in Prism’s API.
+	 * It fetches all the elements that have a `.language-xxxx` class and then calls {@link Prism.highlightElement} on
+	 * each one of them.
+	 *
+	 * This is equivalent to `Prism.highlightAllUnder(document, async, callback)`.
+	 *
+	 * @param {HTMLElement} container The root element, whose descendants that have a `.language-xxxx` class will be highlighted.
+	 * @param {boolean} [async=false] Same as in {@link Prism.highlightAllUnder}.
+	 * @param {Prism.HighlightCallback} [callback] Same as in {@link Prism.highlightAllUnder}.
+	 * @memberof Prism
+	 */
 	highlightAll: function(async, callback) {
 		_.highlightAllUnder(document, async, callback);
 	},
 
+	/**
+	 * Fetches all the descendants of `container` that have a `.language-xxxx` class and then calls
+	 * {@link Prism.highlightElement} on each one of them.
+	 *
+	 * The following hooks will be run:
+	 * 1. `before-highlightall`
+	 * 2. All hooks of {@link Prism.highlightElement} for each element.
+	 *
+	 * @param {HTMLElement} container The root element, whose descendants that have a `.language-xxxx` class will be highlighted.
+	 * @param {boolean} [async=false] Whether each element is to be highlighted asynchronously using Web Workers.
+	 * @param {Prism.HighlightCallback} [callback] An optional callback to be invoked on each element after its highlighting is done.
+	 * @memberof Prism
+	 */
 	highlightAllUnder: function(container, async, callback) {
 		var env = {
 			callback: callback,
@@ -187,6 +248,30 @@ var _ = {
 		}
 	},
 
+	/**
+	 * Highlights the code inside a single element.
+	 *
+	 * The following hooks will be run:
+	 * 1. `before-sanity-check`
+	 * 2. `before-highlight`
+	 * 3. All hooks of {@link Prism.highlightElement}. These hooks will only be run by the current worker if `async` is `true`.
+	 * 4. `before-insert`
+	 * 5. `after-highlight`
+	 * 6. `complete`
+	 *
+	 * @param {HTMLElement} element The element containing the code.
+	 * It must have a class of `language-xxxx` to be processed, where `xxxx` is a valid language identifier.
+	 * @param {boolean} [async=false] Whether the element is to be highlighted asynchronously using Web Workers
+	 * to improve performance and avoid blocking the UI when highlighting very large chunks of code. This option is
+	 * [disabled by default](https://prismjs.com/faq.html#why-is-asynchronous-highlighting-disabled-by-default).
+	 *
+	 * Note: All language definitions required to highlight the code must be included in the main `prism.js` file for
+	 * asynchronous highlighting to work. You can build your own bundle on the
+	 * [Download page](https://prismjs.com/download.html).
+	 * @param {Prism.HighlightCallback} [callback] An optional callback to be invoked after the highlighting is done.
+	 * Mostly useful when `async` is `true`, since in that case, the highlighting is done asynchronously.
+	 * @memberof Prism
+	 */
 	highlightElement: function(element, async, callback) {
 		// Find language
 		var language, grammar, parent = element;
@@ -265,6 +350,25 @@ var _ = {
 		}
 	},
 
+	/**
+	 * Low-level function, only use if you know what you’re doing. It accepts a string of text as input
+	 * and the language definitions to use, and returns a string with the HTML produced.
+	 *
+	 * The following hooks will be run:
+	 * 1. `before-tokenize`
+	 * 2. `after-tokenize`
+	 * 3. `wrap`: On each {@link Prism.Token}.
+	 *
+	 * @param {string} text A string with the code to be highlighted.
+	 * @param {Grammar} grammar An object containing the tokens to use.
+	 *
+	 * Usually a language definition like `Prism.languages.markup`.
+	 * @param {string} language The name of the language definition passed to `grammar`.
+	 * @returns {string} The highlighted HTML.
+	 * @memberof Prism
+	 * @example
+	 * Prism.highlight('var foo = true;', Prism.languages.js, 'js');
+	 */
 	highlight: function (text, grammar, language) {
 		var env = {
 			code: text,
@@ -403,6 +507,21 @@ var _ = {
 		}
 	},
 
+	/**
+	 * This is the heart of Prism, and the most low-level function you can use. It accepts a string of text as input
+	 * and the language definitions to use, and returns an array with the tokenized code.
+	 *
+	 * When the language definition includes nested tokens, the function is called recursively on each of these tokens.
+	 *
+	 * This method could be useful in other contexts as well, as a very crude parser.
+	 *
+	 * @param {string} text A string with the code to be highlighted.
+	 * @param {Grammar} grammar An object containing the tokens to use.
+	 *
+	 * Usually a language definition like `Prism.languages.markup`.
+	 * @returns {Array.<string | Prism.Token>} An array of strings, tokens and other arrays.
+	 * @memberof Prism
+	 */
 	tokenize: function(text, grammar) {
 		var strarr = [text];
 
@@ -421,9 +540,24 @@ var _ = {
 		return strarr;
 	},
 
+	/**
+	 * @namespace
+	 * @memberof Prism
+	 */
 	hooks: {
 		all: {},
 
+		/**
+		 * Adds the given callback to the list of callbacks for the given hook.
+		 *
+		 * The callback will be invoked when the hook it is registered for is run.
+		 * Hooks are usually directly run by a highlight function but you can also run hooks yourself.
+		 *
+		 * One callback function can be registered to multiple hooks and the same hook multiple times.
+		 *
+		 * @param {string} name The name of the hook.
+		 * @param {Prism.hooks.HookCallback} callback The callback function which is given environment variables.
+		 */
 		add: function (name, callback) {
 			var hooks = _.hooks.all;
 
@@ -432,6 +566,14 @@ var _ = {
 			hooks[name].push(callback);
 		},
 
+		/**
+		 * Runs a hook invoking all registered callbacks with the given environment variables.
+		 *
+		 * Callbacks will be invoked synchronously and in the order in which they were registered.
+		 *
+		 * @param {string} name The name of the hook.
+		 * @param {Object.<string, any>} env The environment variables of the hook passed to all callbacks registered.
+		 */
 		run: function (name, env) {
 			var callbacks = _.hooks.all[name];
 
@@ -447,15 +589,50 @@ var _ = {
 
 	Token: Token
 };
-
 _self.Prism = _;
 
+/**
+ * Creates a new token.
+ *
+ * @param {string} type See {@link Prism.Token#type type}
+ * @param {string | Prism.Token | Array.<string|Prism.Token>} content See {@link Prism.Token#content content}
+ * @param {string|string[]} [alias] The alias(es) of the token.
+ * @param {string} [matchedStr=""] A copy of the full string this token was created from.
+ * @param {boolean} [greedy=false] See {@link Prism.Token#greedy greedy}
+ * @class
+ * @memberof Prism
+ */
 function Token(type, content, alias, matchedStr, greedy) {
+	/**
+	 * The type of the token.
+	 *
+	 * This is usually the key of a pattern in a {@link Grammar}.
+	 * @member {string}
+	 */
 	this.type = type;
+	/**
+	 * The strings or tokens contained by this token.
+	 *
+	 * This will be a token stream if the pattern matched also defined an `inside` grammar.
+	 * @member {string | Prism.Token | Array.<string|Prism.Token>}
+	 */
 	this.content = content;
+	/**
+	 * The alias(es) of the token.
+	 * @member {string|string[]}
+	 * @see TokenObject
+	 */
 	this.alias = alias;
-	// Copy of the full string this token was created from
+	/**
+	 *
+	 * @member {number}
+	 */
 	this.length = (matchedStr || "").length|0;
+	/**
+	 * Whether the pattern that created this token is greedy or not.
+	 * @member {boolean}
+	 * @see TokenObject
+	 */
 	this.greedy = !!greedy;
 }