feat(jsdoc): add support for more jsdoc tags

 - Add support for the following jsdoc tags: async, constant, enum, since
 - Improve support for the following jsdoc tags: deprecated, module
 - Add the booleanTagTransform() service for jsdoc tags like '@async' and '@deprecated'
 - Add the moduleTagTransform() service for the jsdoc tag '@module' to cope with jsdoc behaviour when no value is provided (see https://jsdoc.app/tags-module.html)

jsdoc/index.js

@@ -22,9 +22,11 @@ module.exports = new Package('jsdoc', [require('../base')])
 
 .factory(require('./services/code-name-map'))
 .factory(require('./services/code-name'))
+.factory(require('./services/transforms/boolean-tag'))
 .factory(require('./services/transforms/extract-access'))
 .factory(require('./services/transforms/extract-name'))
 .factory(require('./services/transforms/extract-type'))
+.factory(require('./services/transforms/module-tag'))
 .factory(require('./services/transforms/unknown-tag'))
 .factory(require('./services/transforms/whole-tag'))
 .factory(require('./services/transforms/trim-whitespace'))

jsdoc/services/transforms/boolean-tag.js

@@ -0,0 +1,9 @@
+/**
+ * Change the value of a tag to a boolean value (used by jsdoc tags like `@async`).
+ * @param  {Tag} tag The tag to process
+ */
+module.exports = function booleanTagTransform() {
+  return function(doc, tag, value) {
+    return value !== null && value !== undefined;
+  };
+};

jsdoc/services/transforms/boolean-tag.spec.js

@@ -0,0 +1,32 @@
+var transformFactory = require('./boolean-tag');
+
+describe("boolean-tag transform", function() {
+  var transform;
+
+  beforeEach(function() {
+    transform = transformFactory();
+  });
+
+  it("should transform non-null and non-undefined values to `true`", function() {
+    var doc = {}, tag = {};
+
+    var value = '', newValue = transform(doc, tag, value);
+    expect(newValue).toEqual(true);
+
+    var value = 'some text', newValue = transform(doc, tag, value);
+    expect(newValue).toEqual(true);
+
+    var value = {}, newValue = transform(doc, tag, value);
+    expect(newValue).toEqual(true);
+  });
+
+  it("should transform null and undefined values to `false`", function() {
+    var doc = {}, tag = {};
+
+    var value = null, newValue = transform(doc, tag, value);
+    expect(newValue).toEqual(false);
+
+    var value = undefined, newValue = transform(doc, tag, value);
+    expect(newValue).toEqual(false);
+  });
+});

jsdoc/services/transforms/module-tag.js

@@ -0,0 +1,35 @@
+/**
+ * If current tag is a jsdoc `@module` tag without a value, set it to its file projectRelativePath
+ * without the '.js' extension and replacing '/'s with '.'s
+ * @param  {Tag} tag The tag to process
+ */
+module.exports = function moduleTagTransform(log, createDocMessage) {
+  return function(doc, tag, value) {
+    var filePath = doc.fileInfo.relativePath;
+
+    if (tag.name == 'module') {
+
+      // JsDoc `@module` tags does not refer to any code node
+      // TODO: implement this a generic option for any tag to be declared inside tagDefs
+      //   E.g., `{ name: 'module', noCodeNode: true, transforms: [ ... ] }`
+      doc.codeNode = null;
+      doc.codeAncestors = null;
+
+      // Provide default module name if none is already set
+      if (!value && filePath) {
+        value = filePath;
+
+        if (value.endsWith('.js')) {
+          value = value.substring(0, value.length - 3);
+        }
+        value = value.replace(/\//g, '.');
+
+        log.debug(createDocMessage(`Module name automatically set to ${value}`, doc));
+      }
+    } else {
+      log.warn(createDocMessage(`moduleTagTransform() has been called with a non-module jsdoc tag: '${tag.tagName}'`, doc))
+    }
+
+    return value;
+  };
+};

jsdoc/tag-defs/async.js

@@ -0,0 +1,6 @@
+module.exports = function(booleanTagTransform) {
+  return {
+    name: 'async',
+    transforms: [ booleanTagTransform ]
+  };
+};

jsdoc/tag-defs/constant.js

@@ -0,0 +1,7 @@
+module.exports = function(extractTypeTransform, extractNameTransform, wholeTagTransform) {
+  return {
+    name: 'constant',
+    aliases: ['const'],
+    transforms: [ extractTypeTransform, extractNameTransform, wholeTagTransform ]
+  };
+};

jsdoc/tag-defs/deprecated.js

@@ -1,3 +1,6 @@
-module.exports = function() {
-  return { name: 'deprecated' };
-};
+module.exports = function(booleanTagTransform) {
+  return {
+    name: 'deprecated',
+    transforms: [ booleanTagTransform ]
+  };
+};

jsdoc/tag-defs/enum.js

@@ -0,0 +1,6 @@
+module.exports = function(extractTypeTransform) {
+  return {
+    name: 'enum',
+    transforms: [ extractTypeTransform ]
+  };
+};

jsdoc/tag-defs/index.js

@@ -1,30 +1,34 @@
 
 module.exports = [
   require('./access'),
-  require('./private'),
-  require('./protected'),
-  require('./public'),
-  require('./name'),
-  require('./memberof'),
-  require('./param'),
-  require('./property'),
-  require('./propertyof'),
-  require('./returns'),
-  require('./type'),
-  require('./requires'),
-  require('./module'),
-  require('./description'),
-  require('./deprecated'),
-  require('./see'),
-  require('./usage'),
   require('./animations'),
-  require('./constructor'),
+  require('./async'),
   require('./class'),
   require('./classdesc'),
+  require('./constant'),
+  require('./constructor'),
+  require('./deprecated'),
+  require('./description'),
+  require('./enum'),
+  require('./function'),
   require('./global'),
-  require('./namespace'),
   require('./kind'),
-  require('./function'),
+  require('./license'),
+  require('./memberof'),
   require('./method'),
-  require('./license')
+  require('./module'),
+  require('./name'),
+  require('./namespace'),
+  require('./param'),
+  require('./private'),
+  require('./property'),
+  require('./propertyof'),
+  require('./protected'),
+  require('./public'),
+  require('./requires'),
+  require('./returns'),
+  require('./see'),
+  require('./since'),
+  require('./type'),
+  require('./usage')
 ];

jsdoc/tag-defs/index.spec.js

@@ -3,9 +3,9 @@ var tagDefFactories = require('./');
 describe("jsdoc tagdefs", function() {
   it("should contain an array of tagDef factory functions", function() {
     expect(tagDefFactories).toEqual(jasmine.any(Array));
-    expect(tagDefFactories.length).toEqual(27);
+    expect(tagDefFactories.length).toEqual(31);
     tagDefFactories.forEach(function(factory) {
       expect(factory).toEqual(jasmine.any(Function));
     });
   });
-});
+});

jsdoc/tag-defs/module.js

@@ -1,3 +1,6 @@
-module.exports = function() {
-  return { name: 'module' };
-};
+module.exports = function(moduleTagTransform) {
+  return {
+    name: 'module',
+    transforms: [ moduleTagTransform ]
+  };
+};

jsdoc/tag-defs/since.js

@@ -0,0 +1,3 @@
+module.exports = function() {
+  return { name: 'since' };
+};