Merge branch 'master' into scss-multiline

iabw · May 13, 2014 · 4819f56 · 4819f56
2 parents 4606f60 + f1ff5dc
commit 4819f56
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 3 deletions.
diff --git a/History.md b/History.md
@@ -1,5 +1,12 @@
 # Docker Version History
 
+## 0.2.11
+
+ * Change sidebar loading in produced output to fire on DOMContentLoaded - thanks [hhelwich](//github.com/hhelwich)
+ * LiveScript syntax support, thanks to [qgustavor](//github.com/qgustavor).
+ * Add option to ignore inline comments and only process multiline comments - thanks to [jasonseney](//github.com/jasonseney)
+ * Big pile of updates to jsDoc tag handling: alias some types, add default handler for unknown types, and escape HTML properly. Thanks [ErisDS](//github.com/ErisDS)!
+
 ## 0.2.10
 
  * Purely a version bump because npm was having issues publishing 0.2.9

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "author": "JT <[email protected]>",
   "name": "docker",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "dependencies": {
     "mkdirp": "0.3.2",
     "commander": "0.5.2",

diff --git a/res/jsDoc.jst b/res/jsDoc.jst
@@ -71,6 +71,21 @@ if(tags.length){
     </span>
 <%  }
 
+    if(tag.type == 'unknown'){                                      %>
+    <div class="dox_tag_title"><%= tag.name %></div>
+    <div class="dox_tag_detail">
+<%    if(tag.types){
+        for(var j = 0; j < tag.types.length; j += 1){           %>
+      <span class="dox_type"><%= tag.types[j] %></span>
+<%      }
+      }
+
+      if(tag.description){                                      %>
+      <span><%= md(tag.description, true) %></span>
+<%    }                                                         %>
+    </div>
+<%  }
+
     if(tag.type == 'see'){                                      %>
     <div class="dox_tag_title">See</div>
     <div class="dox_tag_detail">

diff --git a/res/script.js b/res/script.js
@@ -210,7 +210,13 @@ function switchTab(tab){
  *
  * When the document is ready, make the sidebar and all that jazz
  */
-window.onload = function(){
+(function (init) {
+  if (window.addEventListener) {
+    window.addEventListener('DOMContentLoaded', init);
+  } else { // IE8 and below
+    window.onload = init;
+  }
+}(function(){
   makeTree(tree, relativeDir, thisFile);
   wireUpTabs();
 
@@ -220,4 +226,5 @@ window.onload = function(){
   }else{
     switchTab('tree');
   }
-};
+}));
+
diff --git a/src/docker.js b/src/docker.js
@@ -632,6 +632,15 @@ Docker.prototype.parseMultiline = function(comment){
   // to remove the type from it.
   function grabType(bits){
     var type = bits.shift();
+    var badChars = /[&<>"'`]/g;
+    var escape = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#x27;",
+      "`": "&#x60;"
+    };
 
     // Carry on adding bits until we reach a closing brace
     while(bits.length && type.indexOf('}') === -1) type += bits.shift();
@@ -644,6 +653,12 @@ Docker.prototype.parseMultiline = function(comment){
       type = type.replace(/\}.*$/,'}');
     }
 
+    function escapeChar(chr) {
+      return escape[chr] || "&amp;";
+    }
+
+    type = type.replace(badChars, escapeChar);
+
     return type.replace(/[{}]/g,'');
   }
 
@@ -660,27 +675,42 @@ Docker.prototype.parseMultiline = function(comment){
       var tagType = tag.type = bits.shift();
 
       switch(tagType){
+        case 'arg':
+        case 'argument':
         case 'param':
           // `@param {typename} paramname Parameter description`
           if(bits[0].charAt(0) == '{') tag.types = grabType(bits).split(/ *[|,\/] */);
           tag.name = bits.shift() || '';
           tag.description = bits.join(' ');
+          tag.type = 'param';
           break;
 
+        case 'returns':
         case 'return':
           // `@return {typename} Return description`
           if(bits[0].charAt(0) == '{') tag.types = grabType(bits).split(/ *[|,\/] */);
           tag.description = bits.join(' ');
+          tag.type = 'return';
           break;
 
         case 'type':
           // `@type {typename}`
           tag.types = grabType(bits).split(/ *[|,\/] */);
           break;
 
+        case 'access':
         case 'api':
           // `@api public` or `@api private` etc.
           tag.visibility = bits.shift();
+          tag.type = 'api';
+          break;
+
+        case 'private':
+        case 'protected':
+        case 'public':
+          // `@public` or `@private` etc.
+          tag.visibility = tagType;
+          tag.type = 'api';
           break;
 
         case 'see':
@@ -692,6 +722,11 @@ Docker.prototype.parseMultiline = function(comment){
             tag.local = bits.join(' ');
           }
           break;
+        default:
+          if(bits[0].charAt(0) == '{') tag.types = grabType(bits).split(/ *[|,\/] */);
+          tag.description = bits.join(' ');
+          tag.name = tagType;
+          tag.type = 'unknown';
       }
 
       return tag;
@@ -822,6 +857,11 @@ Docker.prototype.languages = {
     executables: [ 'coffee' ],
     comment: '#',  multiLine: [ /^\s*#{3}\s*$/m, /^\s*#{3}\s*$/m ], jsDoc: true
   },
+  livescript: {
+    extensions: [ 'ls' ],
+    executables: [ 'lsc' ],
+    comment: '#',  multiLine: [ /\/\*\*?/, /\*\// ], jsDoc: true
+  },
   ruby: {
     extensions: [ 'rb', 'rbw', 'rake', 'gemspec' ],
     executables: [ 'ruby' ],