Merge pull request #255 from ahilles107/develop

Documentation fixes and code formating

build/build.php

@@ -58,7 +58,7 @@ function docs($files, $path, $save) {
 							$block .= "{$split[0]}\n:\t{$split[1]}\n\n";
 							break;
 						case RETURNS:
-							$block .= "###Returns\n".$value."\n\n";
+							$block .= "###Returns\n"."<span class=\"returns\">".$value."</span>\n\n";
 							break;
 						case SEE:
 							$split = preg_split("/\s*,\s*/", $value);
@@ -208,6 +208,7 @@ function merge($files, $path = "", $save) {
 			   "HashMap.js", 
 			   "2D.js", 
 			   "collision.js", 
+			   "hitbox.js", 
 			   "DOM.js",
 			   "html.js",
 			   "storage.js",

build/global.css

@@ -89,7 +89,10 @@ button:active {
 #doc-content { float:left; width:600px }
 
 .doc-top { float:right; font-size:12px; margin-top:10px }
-#doc-content dl { background:#eee; padding:5px; font-size:14px }
+#doc-content dl { background:#eee; padding:10px; font-size:13px; -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px;}
 #doc-content dt { font-weight:bold; font-family:'Courier New', monospace }
 #doc-content dd { margin:0 0 5px 25px }
-.doc-block { margin-top:50px }
+.doc-block { margin-top:50px }
+
+div.doc-contents ul li {display: inline-block; margin: 0px 15px; min-width: 220px;}
+pre code {background-color: whiteSmoke; display: block; padding: 8.5px; margin: -10px 0 18px; line-height: 18px; font-size: 12px; border: 1px solid #CCC; border: 1px solid rgba(0, 0, 0, 0.15); -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; white-space: pre; white-space: pre-wrap; word-wrap: break-word;}

src/2D.js

@@ -527,14 +527,11 @@ Crafty.c("2D", {
 	/**@
 	* #._cascade
 	* @comp 2D
-  * @sign public void ._cascade(e)
+    * @sign public void ._cascade(e)
 	* @param e - Amount to move X
-	* Shift or move the entity by an amount. Use negative values
+	* Shift move or rotate the entity by an amount. Use negative values
 	* for an opposite direction.
 	*/
-	/**
-	* Move or rotate all the children for this entity
-	*/
 	_cascade: function (e) {
 		if (!e) return; //no change in position
 		var i = 0, children = this._children, l = children.length, obj;
@@ -619,13 +616,15 @@ Crafty.c("2D", {
 	* @sign public this .origin(String offset)
 	* @param offset - Combination of center, top, bottom, middle, left and right
 	* Set the origin point of an entity for it to rotate around.
+	* 
 	* @example
 	* ~~~
 	* this.origin("top left")
 	* this.origin("center")
 	* this.origin("bottom right")
 	* this.origin("middle right")
 	* ~~~
+	* 
 	* @see .rotation
 	*/
 	origin: function (x, y) {
@@ -652,6 +651,20 @@ Crafty.c("2D", {
 		return this;
 	},
 
+	/**@
+	* #.flip
+	* @comp 2D
+	* @trigger Change - when the entity has flipped
+	* @sign public this .flip(String dir)
+	* @param dir - Flip direction
+	* 
+	* Flip entity on passed direction
+	* 
+	* @example
+	* ~~~
+	* this.flip("X")
+	* ~~~
+	*/
 	flip: function (dir) {
 		dir = dir || "X";
 		this["_flip" + dir] = true;
@@ -737,10 +750,13 @@ Crafty.c("Gravity", {
 	* @comp Gravity
 	* @sign public this .gravity([comp])
 	* @param comp - The name of a component that will stop this entity from falling
+	* 
 	* Enable gravity for this entity no matter whether comp parameter is not specified, 
 	* If comp parameter is specified all entities with that component will stop this entity from falling.
 	* For a player entity in a platform game this would be a component that is added to all entities
 	* that the player should be able to walk on.
+	* 
+	* @example
 	* ~~~
 	* Crafty.e("2D, DOM, Color, Gravity")
 	*	 .color("red")
@@ -761,7 +777,10 @@ Crafty.c("Gravity", {
 	* @comp Gravity
 	* @sign public this .gravityConst(g)
 	* @param g - gravitational constant
+	* 
 	* Set the gravitational constant to g. The default is .2. The greater g, the faster the object falls.
+	* 
+	* @example
 	* ~~~
 	* Crafty.e("2D, DOM, Color, Gravity")
 	*   .color("red")
@@ -840,6 +859,7 @@ Crafty.c("Gravity", {
 /**@
 * #Crafty.Polygon
 * @category 2D
+* 
 * Polygon object used for hitboxes and click maps. Must pass an Array for each point as an
 * argument where index 0 is the x position and index 1 is the y position.
 *
@@ -865,13 +885,15 @@ Crafty.polygon = function (poly) {
 };
 
 Crafty.polygon.prototype = {
-/**@
+	/**@
 	* #.containsPoint
 	* @comp Crafty.Polygon
 	* @sign public Boolean .containsPoint(Number x, Number y)
 	* @param x - X position of the point
 	* @param y - Y position of the point
+	* 
 	* Method is used to determine if a given point is contained by the polygon.
+	* 
 	* @example
 	* ~~~
 	* var poly = new Crafty.polygon([50,0],[100,100],[0,100]);
@@ -897,7 +919,9 @@ Crafty.polygon.prototype = {
 	* @sign public void .shift(Number x, Number y)
 	* @param x - Amount to shift the `x` axis
 	* @param y - Amount to shift the `y` axis
+	* 
 	* Shifts every single point in the polygon by the specified amount.
+	* 
 	* @example
 	* ~~~
 	* var poly = new Crafty.polygon([50,0],[100,100],[0,100]);
@@ -935,6 +959,7 @@ Crafty.polygon.prototype = {
 * @category 2D
 * Circle object used for hitboxes and click maps. Must pass a `x`, a `y` and a `radius` value.
 *
+*@example
 * ~~~
 * var centerX = 5,
 *     centerY = 10,
@@ -962,13 +987,15 @@ Crafty.circle = function (x, y, radius) {
 };
 
 Crafty.circle.prototype = {
-/**@
+    /**@
 	* #.containsPoint
 	* @comp Crafty.Circle
 	* @sign public Boolean .containsPoint(Number x, Number y)
 	* @param x - X position of the point
 	* @param y - Y position of the point
+	* 
 	* Method is used to determine if a given point is contained by the circle.
+	* 
 	* @example
 	* ~~~
 	* var circle = new Crafty.circle(0, 0, 10);
@@ -991,7 +1018,9 @@ Crafty.circle.prototype = {
 	* @sign public void .shift(Number x, Number y)
 	* @param x - Amount to shift the `x` axis
 	* @param y - Amount to shift the `y` axis
+	* 
 	* Shifts the circle by the specified amount.
+	* 
 	* @example
 	* ~~~
 	* var poly = new Crafty.circle(0, 0, 10);

src/DOM.js

@@ -4,7 +4,7 @@
 * Draws entities as DOM nodes, specifically `<DIV>`s.
 */
 Crafty.c("DOM", {
-/**@
+    /**@
 	* #._element
 	* @comp DOM
 	* The DOM element used to represent the entity.
@@ -61,6 +61,7 @@ Crafty.c("DOM", {
 	* #.getDomId
 	* @comp DOM
 	* @sign public this .getId()
+	* 
 	* Get the Id of the DOM element used to represent the entity.
 	*/
 	getDomId: function() {
@@ -73,6 +74,7 @@ Crafty.c("DOM", {
 	* @trigger Draw - when the entity is ready to be drawn to the stage - { style:String, type:"DOM", co}
 	* @sign public this .DOM(HTMLElement elem)
 	* @param elem - HTML element that will replace the dynamically created one
+	* 
 	* Pass a DOM element to use rather than one created. Will set `._element` to this value. Removes the old element.
 	*/
 	DOM: function (elem) {
@@ -88,6 +90,7 @@ Crafty.c("DOM", {
 	* #.draw
 	* @comp DOM
 	* @sign public this .draw(void)
+	* 
 	* Updates the CSS properties of the node to draw on the stage.
 	*/
 	draw: function () {
@@ -177,6 +180,7 @@ Crafty.c("DOM", {
 	* #.undraw
 	* @comp DOM
 	* @sign public this .undraw(void)
+	* 
 	* Removes the element from the stage.
 	*/
 	undraw: function () {
@@ -194,6 +198,7 @@ Crafty.c("DOM", {
 	* @param value - Value to give the CSS property
 	* @sign public * css(Object map)
 	* @param map - Object where the key is the CSS property and the value is CSS value
+	* 
 	* Apply CSS styles to the element.
 	*
 	* Can pass an object where the key is the style property and the value is style value.
@@ -203,6 +208,7 @@ Crafty.c("DOM", {
 	* The notation can be CSS or JS (e.g. `text-align` or `textAlign`).
 	*
 	* To return a value, pass the property.
+	* 
 	* @example
 	* ~~~
 	* this.css({'text-align', 'center', font: 'Arial'});
@@ -249,15 +255,17 @@ try {
 } catch (e) { }
 
 Crafty.extend({
-/**@
+    /**@
 	* #Crafty.DOM
 	* @category Graphics
+	* 
 	* Collection of utilities for using the DOM.
 	*/
 	DOM: {
 	/**@
 		* #Crafty.DOM.window
 		* @comp Crafty.DOM
+		* 
 		* Object with `width` and `height` values representing the width
 		* and height of the `window`.
 		*/
@@ -277,6 +285,7 @@ Crafty.extend({
 		* @sign public Object Crafty.DOM.inner(HTMLElement obj)
 		* @param obj - HTML element to calculate the position
 		* @returns Object with `x` key being the `x` position, `y` being the `y` position
+		* 
 		* Find a DOM elements position including
 		* padding and border.
 		*/
@@ -301,6 +310,7 @@ Crafty.extend({
 		* @sign public Object Crafty.DOM.getStyle(HTMLElement obj, String property)
 		* @param obj - HTML element to find the style
 		* @param property - Style to return
+		* 
 		* Determine the value of a style on an HTML element. Notation can be
 		* in either CSS or JS.
 		*/

src/HashMap.js

@@ -11,27 +11,32 @@
 	* @comp Crafty.HashMap
 	* @sign public void Crafty.HashMap([cellsize])
 	* @param cellsize - the cell size. If omitted, `cellsize` is 64.
-  * Set `cellsize`.
-  * And create `this.map`.
+	* 
+    * Set `cellsize`.
+    * And create `this.map`.
 	*/
 	var cellsize,
+
 	HashMap = function (cell) {
 		cellsize = cell || 64;
 		this.map = {};
 	},
+
 	SPACE = " ";
 
 	HashMap.prototype = {
 	/**@
 	* #Crafty.map.insert
 	* @comp Crafty.map
-  * @sign public Object Crafty.map.insert(Object obj)
+    * @sign public Object Crafty.map.insert(Object obj)
 	* @param obj - An entity to be inserted.
-  * `obj` is instered in '.map' of the corresponding broad phase cells. An object of the following fields is returned.
-  *
-  * - the object that keep track of cells (keys)
-  * - `obj`
-  * - the HashMap object
+	* 
+    * `obj` is instered in '.map' of the corresponding broad phase cells. An object of the following fields is returned.
+    * ~~~
+    * - the object that keep track of cells (keys)
+    * - `obj`
+    * - the HashMap object
+    * ~~~
 	*/
 		insert: function (obj) {
 			var keys = HashMap.key(obj),
@@ -56,12 +61,13 @@
 	/**@
 	* #Crafty.map.search
 	* @comp Crafty.map
-  * @sign public Object Crafty.map.search(Object rect[, Boolean filter])
+    * @sign public Object Crafty.map.search(Object rect[, Boolean filter])
 	* @param rect - the rectangular region to search for entities.
 	* @param filter - Default value is true. Otherwise, must be false.
-  * - If `filter` is `false`, just search for all the entries in the give `rect` region by broad phase collision. Entity may be returned duplicated.
-  * - If `filter` is `true`, filter the above results by checking that they actually overlap `rect`.
-  * The easier usage is with `filter`=`true`. For performance reason, you may use `filter`=`false`, and filter the result youself. See examples in drawing.js and collision.js
+	* 
+    * - If `filter` is `false`, just search for all the entries in the give `rect` region by broad phase collision. Entity may be returned duplicated.
+    * - If `filter` is `true`, filter the above results by checking that they actually overlap `rect`.
+    * The easier usage is with `filter`=`true`. For performance reason, you may use `filter`=`false`, and filter the result youself. See examples in drawing.js and collision.js
 	*/
 		search: function (rect, filter) {
 			var keys = HashMap.key(rect),
@@ -112,8 +118,11 @@
 	* @sign public void Crafty.map.remove([Object keys, ]Object obj)
 	* @param keys - key region. If omitted, it will be derived from obj by `Crafty.HashMap.key`.
 	* @param obj - need more document.
+	* 
 	* Remove an entity in a broad phase map.
 	* - The second form is only used in Crafty.HashMap to save time for computing keys again, where keys were computed previously from obj. End users should not call this form directly.
+	*
+	* @example 
 	* ~~~
 	* Crafty.map.remove(e);
 	* ~~~
@@ -149,17 +158,20 @@
 	* #Crafty.map.boundaries
 	* @comp Crafty.map
 	* @sign public Object Crafty.map.boundaries()
-  * The return `Object` is of the following format.
+	* 
+    * The return `Object` is of the following format.
+    * ~~~
 	* {
-  *   min: {
-  *     x: val_x,
-  *     y: val_y
-  *   },
-  *   max: {
-  *     x: val_x,
-  *     y: val_y
-  *   }
-  * }
+    *   min: {
+    *     x: val_x,
+    *     y: val_y
+    *   },
+    *   max: {
+    *     x: val_x,
+    *     y: val_y
+    *   }
+    * }
+    * ~~~
 	*/
 		boundaries: function () {
 			var k, ent,
@@ -228,8 +240,10 @@
 * @category 2D
 * Broad-phase collision detection engine. See background information at 
 *
+* ~~~
 * - [N Tutorial B - Broad-Phase Collision](http://www.metanetsoftware.com/technique/tutorialB.html)
 * - [Broad-Phase Collision Detection with CUDA](http.developer.nvidia.com/GPUGems3/gpugems3_ch32.html)
+* ~~~
 * @see Crafty.map
 */
 
@@ -238,9 +252,10 @@
 	* @comp Crafty.HashMap
 	* @sign public Object Crafty.HashMap.key(Object obj)
 	* @param obj - an Object that has .mbr() or _x, _y, _w and _h.
-  * Get the rectangular region (in terms of the grid, with grid size `cellsize`), where the object may fall in. This region is determined by the object's bounding box.
-  * The `cellsize` is 64 by default.
-  * @see Crafty.HashMap.constructor
+    * Get the rectangular region (in terms of the grid, with grid size `cellsize`), where the object may fall in. This region is determined by the object's bounding box.
+    * The `cellsize` is 64 by default.
+    * 
+    * @see Crafty.HashMap.constructor
 	*/
 	HashMap.key = function (obj) {
 		if (obj.hasOwnProperty('mbr')) {