added some docs

dist/jstree.js

@@ -1,15 +1,13 @@
-/*
- * jsTree 2.0.0-alpha
+/**
+ * ## jsTree 2.0.0-alpha ##
  * http://jstree.com/
  *
- * Copyright (c) 2013 Ivan Bozhanov (vakata.com)
+ * Copyright (c) 2013 Ivan Bozhanov (http://vakata.com)
  *
  * Licensed same as jquery - under the terms of the MIT License
  *   http://www.opensource.org/licenses/mit-license.php
  *
  */
-
-/*global jQuery, window, document, setTimeout, setInterval, clearTimeout, clearInterval, console */
 (function ($) {
 	"use strict";
 
@@ -24,41 +22,87 @@
 		ccp_mode = false,
 		themes_loaded = [];
 
+	/**
+	 * ### Static $.jstree object
+	 *
+	 * `$.jstree` holds all jstree related functions and variables
+	 *
+	 * * `version` the jstree version in use
+	 * * `plugins` stores all loaded jstree plugins
+	 * * `defaults` holds the core & plugin's defaults
+	 *
+	 */
 	$.jstree = {
 		version : '2.0.0-alpha',
 		defaults : {
 			plugins : []
 		},
-		plugins : {},
-		create : function (el, options) {
-			// create the new core
-			var tmp = new $.jstree.core(++instance_counter);
-			// extend options with the defaults
-			options = $.extend(true, {}, $.jstree.defaults, options);
-			// each option key except 'core' represents a plugin to be loaded
-			$.each(options.plugins, function (i, k) {
-				if(i !== 'core') {
-					// decorate the object with the plugin
-					tmp = tmp.plugin(k, options[k]);
-				}
-			});
-			// initialize the tree
-			tmp.init(el, options);
-			// return the instance
-			return tmp;
-		},
-		core : function (id) {
-			this._id = id;
-			this._data = {
-				'core' : {
-					'themes' : {}
-				}
-			};
-		},
-		reference : function (needle) {
-			return $(needle).closest('.jstree').data('jstree');
-		}
+		plugins : {}
 	};
+	/**
+	 * `$.jstree.create()` creates a jstree instance
+	 *
+	 * __Parameters__
+	 *
+	 * * `el` - the element to create the instance in
+	 * * `options` - options for the instance, extends `$.jstree.defaults`
+	 *
+	 * __Returns__
+	 * the new jstree instance
+	 */
+	$.jstree.create = function (el, options) {
+		var tmp = new $.jstree.core(++instance_counter);
+		options = $.extend(true, {}, $.jstree.defaults, options);
+		$.each(options.plugins, function (i, k) {
+			if(i !== 'core') {
+				tmp = tmp.plugin(k, options[k]);
+			}
+		});
+		tmp.init(el, options);
+		return tmp;
+	};
+	/**
+	 * `$.jstree.core()` the actual empty class.
+	 *
+	 * Used internally -  to create an instance use either:
+	 *
+	 * * `$.jstree.create(element, options)` or
+	 * * `$(selector).jstree(options)`
+	 *
+	 * __Parameters__
+	 *
+	 * * `id` - the instance index - passed internally
+	 */
+	$.jstree.core = function (id) {
+		this._id = id;
+		this._data = {
+			'core' : {
+				'themes' : {}
+			}
+		};
+	};
+	/**
+	 * `$.jstree.reference()` get an instance by some selector.
+	 *
+	 * __Parameters__
+	 *
+	 * * `needle` - a DOM element / jQuery object to search by.
+	 */
+	$.jstree.reference = function (needle) {
+		return $(needle).closest('.jstree').data('jstree');
+	};
+	/**
+	 * ### jQuery $().jstree method
+	 *
+	 * `$(selector).jstree()` is used to create an instance on the selector or to invoke a command on a instance. `Uses $.jstree.create()` internally.
+	 *
+	 * __Examples__
+	 *
+	 *	$('#container').jstree();
+	 *	$('#container').jstree({ option : value });
+	 *	$('#container').jstree('open_node', '#branch_1');
+	 *
+	 */
 	$.fn.jstree = function (arg) {
 		// check for string argument
 		var is_method = (typeof arg === 'string'),
@@ -78,14 +122,31 @@
 		// if there was a method call with a valid return value - return that, otherwise continue the chain
 		return result !== null && typeof result !== 'undefined' ? result : this;
 	};
-	// :jstree pseudo selector to find all elements with instances
+	/**
+	 * ### jQuery :jstree pseudo selector
+	 *
+	 * `$(':jstree')` is used to find elements containing an instance
+	 *
+	 * __Examples__
+	 *
+	 *	$('div:jstree').each(function () {
+	 *		$(this).jstree('destroy');
+	 *	});
+	 *
+	 */
 	$.expr[':'].jstree = $.expr.createPseudo(function(search) {
 		return function(a) {
 			return $(a).hasClass('jstree') && typeof ($(a).data('jstree')) !== 'undefined';
 		};
 	});
 
-	// CORE
+	/**
+	 * ### jsTree core settings
+	 *
+	 * `$.jstree.defaults.core` stores all defaults for the core.
+	 *
+	 * * `string` should be an object or a function ...
+	 */
 	$.jstree.defaults.core = {
 		strings			: false,
 		check_callback	: true,
@@ -101,7 +162,22 @@
 		},
 		base_height		: false
 	};
+
+	/**
+	 * ### jsTree core methods
+	 */
 	$.jstree.core.prototype = {
+		/**
+		 * `plugin()` is used to decorate an instance with a plugin. Used internally in `$.jstree.create()`.
+		 *
+		 * __Parameters__
+		 *
+		 * * `deco` - the decorator to use
+		 * * `options` - options for the decorator, extends `$.jstree.defaults`
+		 *
+		 * __Returns__
+		 * the decorated jstree instance
+		 */
 		plugin : function (deco, opts) {
 			var Child = $.jstree.plugins[deco];
 			if(Child) {
@@ -3554,11 +3630,6 @@ Does not allow the same name amongst siblings (still a bit experimental).
 	// $.jstree.defaults.plugins.push("wholerow");
 })(jQuery);
 
-/* File: jstree.xml.js
-This plugin makes it possible for jstree to use XML data sources.
-*/
-/* Group: jstree xml plugin */
-/*global ActiveXObject, XSLTProcessor */
 (function ($) {
 	var xsl = {
 		'nest' : '' +

docs/index.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="utf-8">
+	<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+	<title>jsTree API documentation</title>
+
+	<link rel="stylesheet" href="./bootstrap.min.css" />
+	<!--[if lt IE 7]><meta http-equiv="imagetoolbar" content="false" /><![endif]-->
+	<style>
+	html, body { background:#ebebeb; }
+	.container { width:100%; background:white; margin:20px auto; border-radius:5px; box-shadow:0 0 4px silver; max-width:1200px; min-width:320px; }
+	.item { margin:20px; }
+	h2 { font-family:Georgia, serif; }
+	h3 { margin:0px 20px -10px 20px; font-family:Georgia, serif; padding-top:20px; border-top:1px dotted silver; }
+	.docs { padding-top:10px; width:50%; }
+	.code { float:right; width:45%; }
+	.code pre { overflow:auto; }
+	</style>
+</head>
+<body>
+	<div class="container" role="main">
+
+	</div>
+
+	<script src="./jquery.1.9.1.min.js"></script>
+	<script>
+	$(function () {
+		var container = $('.container');
+		$.getJSON('./jstree.json', function (data) {
+			var first = true;
+			$.each(data, function (i, v) {
+				if(first) {
+					container.append('<div style="text-align:center;" class="item clearfix">' + v.description.full + '</div>');
+					first = false;
+					return true;
+				}
+				if(v.ignore) {
+					return true;
+				}
+				if(!v.code) {
+					v.code = '';
+				}
+				if(v.code.indexOf('\n') > 0) {
+					var l = v.code.split('\n')[1].split('\t').length - 1;
+					v.code = new Array(l).join('\t') + v.code;
+					v.code = v.code.replace(new RegExp('^\t{'+(l-1)+'}','mg'), '');
+				}
+				v.code = v.code.replace(/\t/g,'  ')
+				container.append('<div class="item clearfix"><div class="code"><pre>' + v.code + '</pre></div><div class="docs">' + v.description.full + '</div><div>');
+				//container.append(v.description.full);
+			});
+			$('.docs > h3').each(function () {
+				$(this).closest('.item').before($(this));
+			});
+		});
+	});
+	</script>
+</body>
+</html>

gruntfile.js

@@ -50,11 +50,19 @@ module.exports = function(grunt) {
         'globals' : {
           'console' : true,
           'jQuery' : true,
-          'browser' : true
+          'browser' : true,
+          'XSLTProcessor' : true,
+          'ActiveXObject' : true
         }
       },
       beforeconcat: ['src/**/*.js'],
       afterconcat: ['dist/<%= pkg.name %>.js']
+    },
+    dox: {
+      files: {
+        src: ['src/*.js'],
+        dest: 'docs'
+      }
     }
   });
 
@@ -64,7 +72,35 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-contrib-uglify');
   grunt.loadNpmTasks('grunt-contrib-qunit');
 
+
+  grunt.registerMultiTask('dox', 'Generate dox output ', function() {
+
+    var exec = require('child_process').exec,
+        path = require('path'),
+        done = this.async(),
+        doxPath = path.resolve(__dirname),
+        formatter = [doxPath, 'node_modules', '.bin', 'dox'].join(path.sep),
+        str = grunt.file.read('dist/jstree.js');
+
+    str = str.replace(/^\s+\*/mg,'*');
+    str = str.replace(/^\s+\/\/ .*$/mg,'');
+    grunt.file.write('dist/jstree.dox.js', str);
+
+    exec(formatter + ' < "dist/jstree.dox.js" > "docs/jstree.json"', {maxBuffer: 5000*1024}, function(error, stout, sterr){
+      if (error) {
+        grunt.log.error(formatter);
+        grunt.log.error("WARN: "+ error);
+        grunt.file.delete('dist/jstree.dox.js');
+      }
+      if (!error) {
+        grunt.log.writeln('dist/jstree.js doxxed.');
+        grunt.file.delete('dist/jstree.dox.js');
+        done();
+      }
+    });
+  });
+
   // Default task.
-  grunt.registerTask('default', ['jshint:beforeconcat','concat','jshint:afterconcat','copy','uglify','qunit' ]);
+  grunt.registerTask('default', ['jshint:beforeconcat','concat','jshint:afterconcat','copy','uglify','qunit','dox']);
 
 };

package.json

@@ -29,6 +29,7 @@
     "grunt-contrib-jshint": "~0.1.0",
     "grunt-contrib-concat": "~0.1.1",
     "grunt-contrib-copy": "~0.3.2",
-    "grunt-contrib-qunit": "~0.1.0"
+    "grunt-contrib-qunit": "~0.1.0",
+    "dox": "~0.4.2"
   }
 }