Merge pull request #1059 from starwed/doc-kind

Document the  "kind" of thing associated with a docblock

Author: starwed

build/api-gen/doc-components.jsx

@@ -26,8 +26,7 @@ var MarkdownBlock = React.createClass({
   render: function() {
     var raw = this.props.value;
     var rawHtml = this.convert(raw);
-    var key = this.props.key;
-    return <span key={key} className="markdown" dangerouslySetInnerHTML={{__html: rawHtml}} />
+    return <span className="markdown" dangerouslySetInnerHTML={{__html: rawHtml}} />
   }
 })
 
@@ -46,21 +45,23 @@ var ToC = React.createClass({
       }
     }
     catArray.sort(nameSort);
-    var catElements = catArray.map( function(cat, index){return <Category key={cat.name} catName = {cat.name} pages = {cat.pages}/>});
-    return (
+    var catElements = catArray.map( function(cat, index){return <Category key={cat.name} catName = {cat.name} pages = {cat.pages} />});
+    return ( 
       <ul id = "doc-level-one">
         <li><a href="events.html">List of Events</a></li>
-        <Category catName = {primary} pages = {toc.categories[primary].pages}/>
+        <Category catName = {primary} pages = {toc.categories[primary].pages} />
         {catElements}
       </ul>
     )
   }
 
 })
 
+// The logic for choosing the link name and target is complicated due to the inconsistent way these are tagged in source
 var DocLink = React.createClass({
   render: function() {
     var target = this.props.target;
+    var kind = this.props.kind || "missing";
     var linkText, href;
     var parent = (this.props.parentPage) ? this.props.parentPage.main.name : undefined;
     // If the link target starts with the name of the page, assume it is an internal link
@@ -94,14 +95,16 @@ var DocLink = React.createClass({
       linkText = target;
       href = cleanName(target) + ".html";
     }
-    return <a href={href}>{linkText}</a>
+    return <a href={href} className={"kind-" + kind}>{linkText}</a>
   }
 })
 
 var Category = React.createClass({
   render: function() {
-    this.props.pages.sort(stringSort);
-    var pages = this.props.pages.map(function(page, index){return <li key={page}><DocLink target={page}/></li>});
+    this.props.pages.sort(nameSort);
+    var dictionary = this.props.dict;
+    var pages = this.props.pages.map(function(page, index){return <li key={page.name}><DocLink target={page.name} kind={page.kind}/></li>});
+
     return ( 
       <li className="category">
         {this.props.catName}

build/api-gen/dynamic-server.js

@@ -13,7 +13,7 @@ var cleanName = require("./clean-name");
 function startServer(grunt, input){
     var api = grunt.file.readJSON(input),
       index = createIndex(api),
-      pages = index.pages,
+      pages = index.pages,  
       props = {data: api, index: index};
 
     function createPage(selector, filename) {

build/api-gen/index-docs.js

@@ -17,7 +17,7 @@ function createIndex(blocks) {
     if (block.categories) {
       for (var j = 0; j < block.categories.length; j++) {
         if (block.name) {
-          cat(block.categories[j]).pages.push(block.name)
+          cat(block.categories[j]).pages.push( {name: block.name, kind: block.kind});
         }
         comp(block.name).main = block;
       }

build/parseNodes.coffee

@@ -136,9 +136,18 @@ addNode =
 		parent.requires = iterator.current().value
 		iterator.next()
 
+	kind: (parent, iterator)->
+		parent.kind = iterator.current().value
+		iterator.next()
+	
+	private: (parent, iterator)->
+		parent.private = true
+		iterator.next()
+	
+
 	#These are used only in 2d math files, and so don't have much meaning!
 	public: (parent, iterator)->
-		parent.public = true;
+		parent.private = false;
 		iterator.next()
 	class: (parent, iterator)->
 		parent.class = iterator.current().value

build/parseSourceDocs.coffee

@@ -64,17 +64,17 @@ nameRe = /^\s*\#[^\#]/
 emptyRe = /^\s*$/
 
 # Check whether a tag should be greedy or lazy when consuming subsequent lines
+# A lazy tag will stop parsing at a newline
 lazyTag = (tag) ->
     switch tag 
-        when "name", "comp", "category", "example", "sign"
+        when "name", "comp", "category", "example", "sign", "kind", "private"
             true
         else
             false
 
 # Assign each line to a node, throwing away empty lines that aren't directly after untagged lines
-# Guaranteed to leave the buffer in a state where buffer.current() hasn't yet been processed
+# Promises to leave the buffer in a state where buffer.current() hasn't yet been processed
 nextNode = (buffer)->
-
 
     # Find next non-empty line
     while (buffer.isOpen() and buffer.current().indexOf('*/') == -1) and (clean = cleanLine( buffer.current() )).length == 0
@@ -188,7 +188,7 @@ parseNode = (tag, value)->
         }
 
 
-
+ 
 # The top level method: given a list of files, parses each file into an array of docblocks, which are themeselves arrays of nodes
 # Returns one array of all the docblocks parsed
 parse = (files)->

src/controls/controls-system.js

@@ -72,6 +72,7 @@ ToggleInputGroup.prototype = {
 /**@
  * #Controls
  * @category Controls
+ * @kind System
  * 
  * A built-in system for linking specific inputs to general types of input events.
  * 

src/controls/controls.js

@@ -3,6 +3,7 @@ var Crafty = require('../core/core.js');
 /**@
  * #Draggable
  * @category Controls
+ * @kind Component
  * Enable drag and drop of the entity. Listens to events from `MouseDrag` and moves entity accordingly.
  *
  * @see MouseDrag
@@ -130,6 +131,7 @@ Crafty.c("Draggable", {
 /**@
  * #Controllable
  * @category Controls
+ * @kind Component
  *
  * Used to bind methods to generalized input events.
  *
@@ -256,6 +258,7 @@ Crafty.c("Controllable", {
 /**@
  * #Multiway
  * @category Controls
+ * @kind Component
  *
  * Used to bind keys to directions and have the entity move accordingly.
  *
@@ -380,6 +383,7 @@ Crafty.c("Multiway", {
 /**@
  * #Jumper
  * @category Controls
+ * @kind Component
  * @trigger CheckJumping - When entity is about to jump. This event is triggered with the object the entity is about to jump from (if it exists). Third parties can respond to this event and enable the entity to jump.
  *
  * Make the entity jump in response to key events.
@@ -548,6 +552,7 @@ Crafty.c("Jumper", {
 /**@
  * #Fourway
  * @category Controls
+ * @kind Component
  *
  * Move an entity in four directions by using the
  * `Up Arrow`, `Left Arrow`, `Down Arrow`, `Right Arrow` keys or `W`, `A`, `S`, `D`.
@@ -594,6 +599,7 @@ Crafty.c("Fourway", {
 /**@
  * #Twoway
  * @category Controls
+ * @kind Component
  *
  * Move an entity left or right using the `Left Arrow`, `Right Arrow` keys or `D` and `A`
  * and make it jump using `Up Arrow` or `W`.

src/controls/device.js

@@ -5,6 +5,7 @@ Crafty.extend({
     /**@
      * #Crafty.device
      * @category Misc
+     * @kind Property
      *
      * Methods relating to devices such as tablets or phones
      */
@@ -83,6 +84,8 @@ Crafty.extend({
         /**@
          * #Crafty.device.deviceOrientation
          * @comp Crafty.device
+         * @kind Method
+         * 
          * @sign public Crafty.device.deviceOrientation(Function callback)
          * @param callback - Callback method executed once as soon as device orientation is change
          *
@@ -122,6 +125,8 @@ Crafty.extend({
         /**@
          * #Crafty.device.deviceMotion
          * @comp Crafty.device
+         * @kind Method
+         * 
          * @sign public Crafty.device.deviceMotion(Function callback)
          * @param callback - Callback method executed once as soon as device motion is change
          *

src/controls/inputs.js

@@ -10,6 +10,7 @@ Crafty.extend({
     /**@
      * #Crafty.lastEvent
      * @category Input
+     * @kind Property
      * Check which mouse event occured most recently (useful for determining mouse position in every frame).
      *
      * The native [`MouseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) is augmented with additional properties.
@@ -34,6 +35,7 @@ Crafty.extend({
     /**@
      * #Crafty.keydown
      * @category Input
+     * @kind Property
      * Check which keys (referred by `Crafty.keys` key codes) are currently down.
      *
      * @example
@@ -48,6 +50,7 @@ Crafty.extend({
     /**@
      * #Crafty.selected
      * @category Input
+     * @kind Property
      * @trigger CraftyFocus - is triggered when Crafty's stage gets selected
      * @trigger CraftyBlur - is triggered when Crafty's stage is no longer selected
      *
@@ -78,6 +81,7 @@ Crafty.extend({
     /**@
      * #Crafty.multitouch
      * @category Input
+     * @kind Method
      * @sign public this .multitouch(Boolean bool)
      * @param bool - Turns multitouch on and off.  The initial state is off (false).
      *
@@ -132,6 +136,8 @@ Crafty.extend({
     /**@
      * #Crafty.mouseDispatch
      * @category Input
+     * @private
+     * @kind Method
      *
      * Internal method which dispatches mouse events received by Crafty.
      *
@@ -230,6 +236,8 @@ Crafty.extend({
     /**@
      * #Crafty.touchDispatch
      * @category Input
+     * @kind Method
+     * @private
      *
      * Internal method which dispatches touch events received by Crafty (crafty.stage.elem).
      * The touch events get dispatched to the closest entity to the source of the event (if available).
@@ -416,6 +424,8 @@ Crafty.extend({
     /**@
      * #Crafty.findPointerEventTargetByComponent
      * @category Input
+     * @kind Method
+     * @private
      * 
      * @sign public this .findPointerEventTargetByComponent(String comp, Event e[, Object target])
      * Finds closest entity with certain component at a given event.
@@ -502,6 +512,8 @@ Crafty.extend({
     /**@
      * #Crafty.mouseWheelDispatch
      * @category Input
+     * @kind Method
+     * @private
      *
      * Internal method which dispatches mouse wheel events received by Crafty.
      * @trigger MouseWheelScroll - is triggered when mouse is scrolled on stage - { direction: +1 | -1} - Scroll direction (up | down)
@@ -579,6 +591,8 @@ Crafty.extend({
     /**@
      * #Crafty.keyboardDispatch
      * @category Input
+     * @kind Method
+     * @private
      *
      * Internal method which dispatches keyboard events received by Crafty.
      * @trigger KeyDown - is triggered for each entity when the DOM 'keydown' event is triggered. - { key: `Crafty.keys` keyCode (Number), originalEvent: original KeyboardEvent } - Crafty's KeyboardEvent
@@ -706,6 +720,7 @@ Crafty._preBind("CraftyStop", function () {
 /**@
  * #Mouse
  * @category Input
+ * @kind Component
  *
  * Provides the entity with mouse related events.
  *
@@ -771,6 +786,7 @@ Crafty.c("Mouse", {
 /**@
  * #Touch
  * @category Input
+ * @kind Component
  * Provides the entity with touch related events
  * @trigger TouchStart - when entity is touched - TouchPoint
  * @trigger TouchMove - when finger is moved over entity - TouchPoint
@@ -817,6 +833,8 @@ Crafty.c("Touch", {
 /**@
  * #AreaMap
  * @category Input
+ * @kind Component
+ * 
  * Component used by Mouse and Touch.
  * Can be added to other entities for use with the Crafty.findClosestEntityByComponent method.
  * 
@@ -848,6 +866,7 @@ Crafty.c("AreaMap", {
     /**@
      * #.areaMap
      * @comp AreaMap
+     * @kind Method
      *
      * @trigger NewAreaMap - when a new areaMap is assigned - Crafty.polygon
      *
@@ -904,6 +923,8 @@ Crafty.c("AreaMap", {
 /**@
  * #Button
  * @category Input
+ * @kind Component
+ * 
  * Provides the entity with touch or mouse functionality, depending on whether this is a pc 
  * or mobile device, and also on multitouch configuration.
  *
@@ -921,6 +942,8 @@ Crafty.c("Button", {
 /**@
  * #MouseDrag
  * @category Input
+ * @kind Component
+ * 
  * Provides the entity with drag and drop mouse events.
  * @trigger Dragging - is triggered each frame the entity is being dragged - MouseEvent
  * @trigger StartDrag - is triggered when dragging begins - MouseEvent
@@ -962,6 +985,8 @@ Crafty.c("MouseDrag", {
     /**@
      * #.startDrag
      * @comp MouseDrag
+     * @kind Method
+     * 
      * @sign public this .startDrag(void)
      *
      * Make the entity produce drag events, essentially making the entity follow the mouse positions.
@@ -983,6 +1008,8 @@ Crafty.c("MouseDrag", {
     /**@
      * #.stopDrag
      * @comp MouseDrag
+     * @kind Method
+     * 
      * @sign public this .stopDrag(void)
      *
      * Stop the entity from producing drag events, essentially reproducing the drop.
@@ -1005,6 +1032,7 @@ Crafty.c("MouseDrag", {
 /**@
  * #Keyboard
  * @category Input
+ * @kind Component
  *
  * Provides entity with keyboard events.
  * @trigger KeyDown - is triggered for each entity when the DOM 'keydown' event is triggered. - { key: `Crafty.keys` keyCode (Number), originalEvent: original KeyboardEvent } - Crafty's KeyboardEvent
@@ -1038,6 +1066,8 @@ Crafty.c("Keyboard", {
     /**@
      * #.isDown
      * @comp Keyboard
+     * @kind Method
+     * 
      * @sign public Boolean isDown(String keyName)
      * @param keyName - Name of the key to check. See `Crafty.keys`.
      * @sign public Boolean isDown(Number keyCode)

src/controls/keycodes.js

@@ -5,6 +5,8 @@ Crafty.extend({
     /**@
      * #Crafty.keys
      * @category Input
+     * @kind Property
+     * 
      * Object of key names and the corresponding Unicode key code.
      *
      * ~~~
@@ -199,6 +201,8 @@ Crafty.extend({
     /**@
      * #Crafty.mouseButtons
      * @category Input
+     * @kind Property
+     * 
      * An object mapping mouseButton names to the corresponding button ID.
      * In all mouseEvents, we add the `e.mouseButton` property with a value normalized to match e.button of modern webkit browsers:
      *