More work on JSD format

doc/build.js

@@ -2,7 +2,7 @@ var fs = require("fs");
 var path = require("path");
 var panino = require("panino");
 var srcPath = __dirname + "/../lib/ace";
-var buildType = process.argv.splice(2)[0];buildType
+var buildType = process.argv.splice(2)[0];
 
 var options = {
   title       : "Ace API",
@@ -35,8 +35,7 @@ var options = {
   assets      : "./resources/ace/skeleton",
   additionalObjs : "./additionalObjs.json",
   exclude     : ["**/*_test.js", "**/mode/**", "default_commands.js", "multi_select_commands.js", "**/test/**", "**/theme/**", "**/worker/**"],
-  index       : "./index.md",
+  index       : "./index.md"
-  disableTests: true
 };
 
 files = [srcPath];

doc/resources/ace/skeleton/javascripts/ux.js

@@ -22,7 +22,7 @@ $(function () {
             if (query) {
                 input.value = "";
                 input.blur();
-                var url = "https://www.google.com/search?q=" + encodeURIComponent("site:ace.ajax.org/api" + " " + query);
+                var url = "https://www.google.com/search?q=" + encodeURIComponent("site:ace.ajax.org" + " " + query);
                 window.open(url);
             }
             return false;

doc/resources/ace/templates/ace_menu.jade

@@ -1,59 +0,0 @@
-div#well
-   form(id='searchbox', action='', class='navbar-search')    
-     input(class='search-query span3', name='query', type='text', placeholder="Search the API", title="Search across all the documentation")
-
-   ul.menu
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="ace.html#nav=api") Ace
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="anchor.html#nav=api") Anchor
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="background_tokenizer.html#nav=api") BackgroundTokenizer     
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="document.html#nav=api") Document    
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="edit_session.html#nav=api") EditSession                                                    
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="editor.html#nav=api") Editor
-
-      //- probably not needing doc a(class="menuLink namespace", href="multi_select.html#nav=api") MultiSelect
-
-      //- not actually doc'ed yet a(class="menuLink namespace", href="placeholder.html#nav=api") PlaceHolder
-
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="range.html#nav=api") Range
-
-      //- not actually doc'ed yet a(class="menuLink namespace", href="renderloop.html#nav=api") RenderLoop
-
-                                     
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="scrollbar.html#nav=api") Scrollbar
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="search.html#nav=api") Search                     
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="selection.html#nav=api") Selection   
-
-      //- not actually doc'ed yet  a(class="menuLink namespace", href="split.html#nav=api") Split
-
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="token_iterator.html#nav=api") TokenIterator
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="tokenizer.html#nav=api") Tokenizer
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="undomanager.html#nav=api") UndoManager
-      li
-         div.menu-item
-            a(class="menuLink namespace", href="virtual_renderer.html#nav=api") VirtualRenderer

doc/resources/ace/templates/layout.jade

@@ -1,4 +1,4 @@
-include ../../common_layout
+include common_layout
 include lib
 
 #documentation.span8

doc/resources/ace/templates/lib.jade

@@ -12,6 +12,7 @@ mixin article(obj, parents)
   if typeof obj === 'string'
     obj = list[obj]
 
+  if (obj.private !== true && obj.name.charAt(0) !== "$")
     title = obj.path + (obj.type ? ' (' + obj.type + ')' : '')
     article.article(id=obj.path, data-title=title)
       if obj.type === 'section' || obj.type === 'namespace' || obj.type === 'class' || obj.type === 'mixin'
@@ -24,55 +25,7 @@ mixin article(obj, parents)
             .memberContent
               mixin markdown(obj.description)
       
-      collection = obj.children.filter(function(x){return x.type === 'namespace'});
-      if collection.length
-        .section.namespaces
-          // 
-            h3 Namespaces
-            .memberContent
-              mixin short_description_list(collection)
-
-      collection = obj.children.filter(function(x){return x.type === 'mixin'});
-      if collection.length
-        .section.mixins
-          // 
-            h3 Mixins
-            .memberContent
-              mixin short_description_list(collection)
-
-      if obj.type === 'class'
-
-        if obj.superclass
-          .section.superclass
-            // h3 
-              Superclass
-              .memberContent
-                mixin link(obj.superclass)
-
-        if obj.subclasses.length
-          .section.subclasses
-            // h3 
-              Subclasses
-              .memberContent
-                mixin links(obj.subclasses)
-
-      if obj.included_mixins
-        .section.mixins
-          // h3 
-            Includes
-            .memberContent
-              mixin links(obj.included_mixins)
-
-      collection = obj.children.filter(function(x){return x.type === 'utility'})
-      if collection.length
-        .section.utilities
-          // h3 
-            Utilities
-            .memberContent
-              mixin links(collection)
-    
       else
-
         .section.method
           .memberContent
             if obj.signatures
@@ -92,6 +45,12 @@ mixin article(obj, parents)
                       -if (loops == 0)
                         -loops = 1 // ensure that we only print ONE meta info UL per signature (some methods have multiple signatures)
                         ul.metaInfo
+                            if obj.incomplete
+                              li
+                                span.label.incomplete Incomplete
+                            if obj.experimental
+                              li
+                                span.label.experimental Experimental
                             if obj.readonly
                               li
                                 span.label.read-only Read-Only
@@ -117,15 +76,17 @@ mixin article(obj, parents)
                             else if obj.aliases.length
                               li
                                 span.label.alias.multiple
-                                | Aliased as: 
+                                  | Aliased as:
+                                  ul.alias
                                     for alias in obj.aliases
-                                    mixin link(alias) 
+                                      li
+                                        mixin link(alias)
 
                             if obj.related_to
                               li
                                 span.label.related-to
-                                | Related to: 
+                                  | Related to 
-                                obj.related_to 
+                                  mixin link(obj.related_to, ["relatedToLink"])  
                                     
             div.sideToggler
 

doc/resources/common_layout.jade

@@ -1,57 +0,0 @@
--var dirPrefix = "./";
--var sitePrefix = "../doc/site/";
--var landingPage = 'false'
--var versions = []
-
-mixin doctype
-    !!! 5
-
-    <!--[if lt IE 7]> <html class="no-js ie6 oldie" lang="en"> <![endif]-->
-    <!--[if IE 7]> <html class="no-js ie7 oldie" lang="en"> <![endif]-->
-    <!--[if IE 8]> <html class="no-js ie8 oldie" lang="en"> <![endif]-->
-    <!--[if gt IE 8]><!--> <html class="no-js" lang="en"> <!--<![endif]-->
-
-mixin head
-    meta(http-equiv='Content-Type', content='text/html; charset=UTF-8')
-
-    -if (isIndex)
-        title #{title}
-    -else
-        title #{classId} - #{title}
-
-    meta(name="generator", content="panino-doc-build")
-    meta(name="description", content="Ace API documentation for the online code editor")
-    meta(name="author", content="Garen J. Torikian")
-
-    script(src="#{dirPrefix}resources/javascripts/jquery.js")
-    script(src='#{sitePrefix}/js/main.js')
-    link(rel='stylesheet', media='all and (max-device-width: 480px)', href='doc/site/iphone.css')
-    link(rel='stylesheet', media='all and (min-device-width: 481px) and (max-device-width: 1024px)', href='doc/site/iphone.css')
-    link(href='#{dirPrefix}resources/ace/skeleton/images/favicon.ico', rel='icon', type='image/x-icon')
-
-    link(rel="stylesheet", href="#{dirPrefix}resources/csses/bootstrap.min.css")
-    link(href='#{sitePrefix}/style.css', rel='stylesheet', type='text/css')
-    link(rel="stylesheet", href="#{dirPrefix}resources/csses/ace_api.css")
-    link(rel="stylesheet", href="#{dirPrefix}resources/csses/font-awesome.css")
-
-    link(href="#{dirPrefix}resources/images/favicon.ico", rel="icon", type="image/x-icon")
-
-    script(src='#{dirPrefix}resources/javascripts/bbq.js')
-    script(src="#{dirPrefix}resources/javascripts/jquery.collapse.js")
-    script(src="#{dirPrefix}resources/javascripts/jquery.cookie.js")
-    script(src="#{dirPrefix}resources/javascripts/bootstrap.js")
-
-
-mixin endingScripts
-    script(defer, src="#{dirPrefix}resources/javascripts/ux.js")
-    script(src="#{dirPrefix}resources/javascripts/clicker.js")
-    script(src="#{dirPrefix}resources/javascripts/jquery-scrollspy.js")
-    script(defer, src="#{dirPrefix}resources/javascripts/disqus-ext.js")
-    script(defer, src="#{dirPrefix}resources/javascripts/ga.js")
-
-mixin identifyBuild(tree, type)
-        landingPage = 'true'
-        -dirPrefix = './'
-
-mixin markdown(text, inline)
-    != markdown(text, inline)

lib/ace/edit_session.js

@@ -467,7 +467,7 @@ var EditSession = function(text, mode) {
 
     /**
     * Returns `true` if soft tabs are being used, `false` otherwise.
-    * @returns Boolean
+    * @returns {Boolean}
     **/
     this.getUseSoftTabs = function() {
         return this.$useSoftTabs;
@@ -573,7 +573,7 @@ var EditSession = function(text, mode) {
 
     /**
     * Sets a breakpoint on every row number given by `rows`. This function also emites the `'changeBreakpoint'` event.
-    * @param {[Number]} rows An array of row indicies
+    * @param {Number} rows An array of row indicies
     *
     *
     *
@@ -732,7 +732,7 @@ var EditSession = function(text, mode) {
         var id = this.addMarker(range, clazz, "fullLine", inFront);
         range.id = id;
         return range;
-    },
+    };
    
     /*
      * Error:
@@ -1593,7 +1593,7 @@ var EditSession = function(text, mode) {
 
     /**
     * Returns `true` if wrap mode is being used; `false` otherwise.
-    * @returns Boolean
+    * @returns {Boolean}
     **/
     this.getUseWrapMode = function() {
         return this.$useWrapMode;

lib/ace/editor.js

@@ -52,7 +52,7 @@ var defaultCommands = require("./commands/default_commands").commands;
  *
  * The main entry point into the Ace functionality. 
  *
- * The `Editor` manages the `[[EditSession]]` (which manages `[[Document]]`s), as well as the `[[VirtualRenderer]]`, which draws everything to the screen. 
+ * The `Editor` manages the [[EditSession]] (which manages [[Document]]s), as well as the [[VirtualRenderer]], which draws everything to the screen. 
  *
  * Event sessions dealing with the mouse and keyboard are bubbled up from `Document` to the `Editor`, which decides what to do with them.
  * @class Editor
@@ -1022,7 +1022,6 @@ var Editor = function(renderer, session) {
      * @param {Boolean} enabled Enables or disables behaviors
      * 
      * 
-     * Specifies whether to use behaviors or not. ["Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.]{: #BehaviorsDef}
      **/
     this.setBehavioursEnabled = function (enabled) {
         this.$modeBehaviours = enabled;
@@ -1312,8 +1311,8 @@ var Editor = function(renderer, session) {
     };
 
     /**
-     * Works like [[Editor.getTokenAt]], except it returns a number.
+     * Works like [[EditSession.getTokenAt]], except it returns a number.
-     * @returns Number
+     * @returns {Number}
      **/
     this.getNumberAt = function( row, column ) {
         var _numberRx = /[\-]?[0-9]+(?:\.[0-9]+)?/g
@@ -1337,7 +1336,7 @@ var Editor = function(renderer, session) {
     
     /**
      * Editor.modifyNumber(amount) 
-     * @param [Number] amount The value to change the numeral by (can be negative to decrease value)
+     * @param {Number} amount The value to change the numeral by (can be negative to decrease value)
      *
      * If the character before the cursor is a number, this functions changes its value by `amount`.
      **/