Merge pull request #47 from qbradq/master

Event Support, Fixes
cbou · Mar 29, 2016 · fd7a793 · fd7a793
2 parents 8777429 + 734157e
commit fd7a793
Show file tree

Hide file tree

Showing 5 changed files with 92 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -48,6 +48,11 @@ Here is the list of supported tags:
  * @method name
  * @class name
  * @function name
+ * @event
+ * @type {type}
+ * @property {type} name Message
+ * @fires event
+ * @listens event
 
 Javascript comments should be like this:
 

diff --git a/lib/formatter.js b/lib/formatter.js
@@ -14,31 +14,39 @@ formatter.format = function (docfile) {
     var paramTags = [];
     var returnTags = [];
     var throwsTags = [];
+    var fires = [];
+    var listens = [];
     var tagDeprecated = false;
     var tagName = '';
     var tagClass = '';
     var tagFunction = '';
     var tagMethod = '';
     var tagNamespace = '';
+    var tagEvent = '';
     var tagSee = '';
     var tagVersion = '';
     var tagAuthor = '';
+    var tagType = '';
 
     javadoc.tags.forEach(function(tag){
 
       if (tag.type == 'param') {
-        tag.joinedTypes = tag.types.join('|').replace('<', '\\<');
+        tag.joinedTypes = tag.types.join('|').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;');
         paramTags.push(tag);
         paramStr.push(tag.name);
       } else if (tag.type == 'property') {
-        tag.joinedTypes = tag.types.join('|').replace('<', '\\<');
+        tag.joinedTypes = tag.types.join('|').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;');
         propertyTags.push(tag);
       } else if (tag.type == 'return' || tag.type == 'returns') {
-        tag.joinedTypes = tag.types.join('|').replace('<', '\\<');
+        tag.joinedTypes = tag.types.join('|').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;');
         returnTags.push(tag);
       } else if (tag.type == 'throws') {
-        tag.joinedTypes = tag.types.join('|').replace('<', '\\<');
+        tag.joinedTypes = tag.types.join('|').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;');
         throwsTags.push(tag);
+      } else if (tag.type == 'fires') {
+        fires.push(tag.string);
+      } else if (tag.type == 'listens') {
+        listens.push(tag.string);
       } else if (tag.type == 'namespace') {
         type = 'namespace';
         tagNamespace = tag.string;
@@ -53,6 +61,9 @@ formatter.format = function (docfile) {
         tagFunction = tag.string;
       } else if (tag.type == 'name') {
         tagName = tag.string;
+      } else if (tag.type == 'event') {
+        type = 'event';
+        tagEvent = tag.string;
       } else if (tag.type == 'see') {
         tagSee = tag.url ? tag.url : tag.local;
       } else if (tag.type == 'version') {
@@ -61,6 +72,8 @@ formatter.format = function (docfile) {
         tagDeprecated = true;
       } else if (tag.type == 'author') {
         tagAuthor = tag.string;
+      } else if (tag.type == 'type') {
+        tagType = tag.types.join('|').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;');
       }
     });
 
@@ -69,6 +82,7 @@ formatter.format = function (docfile) {
          : tagClass !== '' ? tagClass
          : tagFunction !== '' ? tagFunction
          : tagNamespace !== '' ? tagNamespace
+         : tagEvent !== '' ? tagEvent
          : name;
 
     description = javadoc.description.full
@@ -93,16 +107,21 @@ formatter.format = function (docfile) {
       , propertyTags: propertyTags
       , returnTags: returnTags
       , throwsTags: throwsTags
+      , fires: fires
+      , listens: listens
       , author: tagAuthor
       , version: tagVersion
       , see: tagSee
       , deprecated: tagDeprecated
+      , tagType: tagType
 
       , type: type
       , isMethod: type === 'method'
       , isFunction: type === 'function'
       , isClass: type === 'class'
       , isNamespace: type === 'namespace'
+      , isEvent: type === 'event'
+      , hasType: tagType !== ''
       , description: description
       , ignore: javadoc.ignore
       , raw: javadoc

diff --git a/templates/template.md.ejs b/templates/template.md.ejs
@@ -8,7 +8,7 @@
         <? if (comment.isMethod || comment.isFunction) { ?>
           ## <?= comment.name ?>(<?= comment.paramStr ?>)
         <? } else { ?>
-          ## <?= comment.name ?>
+          ## <?= comment.name ?> <? if (comment.hasType) { ?> <?= comment.tagType ?> <? } ?>
         <? } ?>
       <? } ?>
 
@@ -48,6 +48,28 @@
           *<? if (returnTag.types.length > 0) { ?> **<?= returnTag.joinedTypes ?>**<? } ?> <?= returnTag.description ?>
         <? }) ?>
       <? } ?>
+
+      <? if (comment.fires.length > 0) { ?>
+        ### Fires:
+        <? comment.fires.forEach(function(event) { ?>
+          * **<?= event ?>**
+        <? }) ?>
+      <? } ?>
+
+      <? if (comment.listens.length > 0) { ?>
+        ### Listens:
+        <? comment.listens.forEach(function(event) { ?>
+          * **<?= event ?>**
+        <? }) ?>
+      <? } ?>
+
+      <? if (comment.throwsTags.length > 0) { ?>
+        ### Throws:
+        <? comment.throwsTags.forEach(function(throws) { ?>
+          * **<?= throws.joinedTypes ?>** <?= throws.description ?>
+        <? }) ?>
+      <? } ?>
+
     <? } ?>
   <? }) ?>
 

diff --git a/test/escapeComplexTypes-test.js b/test/escapeComplexTypes-test.js
@@ -8,9 +8,9 @@ describe('Markdox', function() {
     markdox.process(file, function(err, output) {
       should.not.exist(err);
 
-      output.should.match(/Promise.\\<Object>/);
-      output.should.match(/Promise.\\<Array>/);
-      output.should.match(/Array.\\<Object>/);
+      output.should.match(/Promise.&lt;Object&gt;/);
+      output.should.match(/Promise.&lt;Array&gt;/);
+      output.should.match(/Array.&lt;Object&gt;/);
 
       done();
     });

diff --git a/test/fixtures/events.js b/test/fixtures/events.js
@@ -0,0 +1,38 @@
+/**
+ * A function in an evented system.
+ * 
+ * @fires someEvent
+ * @fires someOtherEvent
+ * @listens someGlobalEvent
+ * @listens SomeClass#event:myEvent
+ * @throws {Error} Throws on error
+ */
+function foo() {}
+
+/**
+ * Some random event.
+ * 
+ * @event someEvent
+ * @type {String}
+ */
+
+/**
+ * Some other random event.
+ * 
+ * @event someOtherEvent
+ * @type {Object}
+ * @property {String} type The type of event
+ * @property {boolean} important Is this event important?
+ */
+
+/**
+ * A global event with no defined type.
+ * 
+ * @event someGlobalEvent
+ */
+
+/**
+ * A class-specific event
+ * 
+ * @event SomeClass#event:MyEvent
+ */