dgeni-packages - npm Package Compare versions

Comparing version 0.5.0 to 0.6.0

CHANGELOG.md

@@ -0,1 +1,33 @@
+## v0.6.0 03/07/2014
+
+**New Features**
+
+* feat(tagParser): only ignore tags that are defined with ignore property 59492bea
+* feat(jsdoc tags): improve jsdoc tag coverage  d8eb2b43
+* feat(PartialNames): getLink disambiguates docs by area  6da98dd5
+* feat(jsdoc/compute-paths): add new processor  23cc829a
+* feat(partial-names): add removeDoc method 746a0bc7
+* test(link handler): fix test, since the handler now throws on error a15053ab
+
+**Bug Fixes**
+
+* fix(compute-paths): ensure contentsFolder is applied correctly  301877fc
+* fix(filter-ngdocs processor): run before tags are extracted a090cf49
+
+**Refactorings**
+
+* refact(ngdoc/id tag def): move functionality to its own doc processor 268ac3bd
+* refact(partial-name processor): move adding docs to own processor 8684226b
+
+**BREAKING CHANGE**
+
+* If you relied on undefined tags being quietly ignored
+your processing will now fail.  You should add new tag defintions for
+all tags that you wish to ignore of the form:
+
+```
+{ name: 'tag-to-ignore', ignore: true }
+```
+
+
 ## v0.5.0 03/07/2014
@@ -2,0 +34,0 @@

examples/spec/processors/examples-generate.spec.js

 var plugin = require('../../processors/examples-generate');
-var configurer = require('dgeni/lib/utils/config');
+var Config = require('dgeni/lib/utils/config').Config;
 var _ = require('lodash');
@@ -8,3 +8,3 @@
   beforeEach(function() {
-    var config = configurer.load();
+    var config = _.extend(Config);
     config.set('processing.examples.templateFolder', 'examples');
@@ -11,0 +11,0 @@ config.set('deployment.environments', [

examples/spec/processors/examples-parse.spec.js

 var rewire = require('rewire');
 var plugin = rewire('../../processors/examples-parse');
-var configurer = require('dgeni/lib/utils/config');
+var Config = require('dgeni/lib/utils/config').Config;
 var log = require('winston');
@@ -10,5 +10,6 @@ var _ = require('lodash');
   beforeEach(function() {
+    var config = _.extend(Config);
     var injectables = { value: function() { } };
     log.level = 'error';
-    plugin.init(configurer.load(), injectables);
+    plugin.init(config, injectables);
   });
@@ -15,0 +16,0 @@

jsdoc/index.js

@@ -9,2 +9,3 @@ module.exports = function(config) {
     require('./processors/tag-extractor'),
+    require('./processors/compute-path'),
     require('./processors/nunjucks-renderer'),
@@ -11,0 +12,0 @@ require('./processors/escaped-comments'),

jsdoc/lib/TagCollection.js

@@ -20,3 +20,3 @@ var _ = require('lodash');
   addTag: function(tag) {
-    if ( !tag.errors ) {
+    if ( !tag.errors && tag.tagDef ) {
       this.tags.push(tag);
@@ -23,0 +23,0 @@

jsdoc/lib/tagParser.js

@@ -30,3 +30,3 @@ var _ = require('lodash');
     var lineNumber = 0;
-    var line, match;
+    var line, match, tagDef;
     var descriptionLines = [];
@@ -54,8 +54,8 @@ var current;          // The current that that is being extracted
       // We ignore tags if we are in a code block
-      if ( !inCode ) {
-        match = TAG_MARKER.exec(line);
-        if ( match && tagDefMap[match[1]] ) {
-          current = new Tag(tagDefMap[match[1]], match[1], match[2], startingLine + lineNumber);
-          break;
-        }
+      match = TAG_MARKER.exec(line);
+      tagDef = match && tagDefMap[match[1]];
+      if ( !inCode && match && ( !tagDef || !tagDef.ignore ) ) {
+        // Only store tags that are unknown or not ignored
+        current = new Tag(tagDef, match[1], match[2], startingLine + lineNumber);
+        break;
       }
@@ -81,5 +81,6 @@
       match = TAG_MARKER.exec(line);
-      if ( !inCode && match && tagDefMap[match[1]] ) {
+      tagDef = match && tagDefMap[match[1]];
+      if ( !inCode && match && (!tagDef || !tagDef.ignore) ) {
         storeTag(current);
-        current = new Tag(tagDefMap[match[1]], match[1], match[2], startingLine + lineNumber);
+        current = new Tag(tagDef, match[1], match[2], startingLine + lineNumber);
       } else {
@@ -86,0 +87,0 @@ current.description = current.description ? (current.description + '\n' + line) : line;

jsdoc/lib/tagProcessors/index.js

 module.exports = [
+  require('./unknownProcessor'),
   require('./trimProcessor'),
@@ -3,0 +4,0 @@ require('./typeProcessor'),

jsdoc/lib/tagProcessors/nameProcessor.js

@@ -38,3 +38,3 @@ var _ = require('lodash');
 module.exports = function(tag) {
-  if ( tag.tagDef.canHaveName ) {
+  if ( tag.tagDef && tag.tagDef.canHaveName ) {
     try {
@@ -41,0 +41,0 @@ extractName(tag);

jsdoc/lib/tagProcessors/typeProcessor.js

@@ -14,3 +14,3 @@ // Much of this code was inspired by or simply copied from the JSDOC project.
   try {
-    if ( tag.tagDef.canHaveType ) {
+    if ( tag.tagDef && tag.tagDef.canHaveType ) {
       extractTypeExpression(tag);
@@ -17,0 +17,0 @@ }

jsdoc/processors/compute-path.js

@@ -11,3 +11,6 @@ var _ = require('lodash');
   init: function(config) {
-    contentsFolder = config.get('rendering.contentsFolder', 'contents');
+    contentsFolder = config.get('rendering.contentsFolder');
+    if ( !contentsFolder ) {
+      throw new Error('Invalid configuration. You must provide config.rendering.contentsFolder');
+    }
   },
@@ -14,0 +17,0 @@ process: function(docs) {

jsdoc/spec/lib/tagParser.spec.js

 var tagParserFactory = require('../../lib/tagParser');
 
-describe("simple-tag-parser", function() {
+describe("tagParser", function() {
   describe("tagParserFactory", function() {
@@ -13,7 +13,8 @@ it("should accept a set of tag-definitions and return a configured tagParser", function() {
   describe("tagParser", function() {
-    it("should only return tags that are passed in as definitions", function() {
+    it("should only return tags that are not ignored", function() {
       var tagDefinitions = [
         { name: 'id' },
         { name: 'description' },
-        { name: 'param' }
+        { name: 'param' },
+        { name: 'other-tag', ignore: true }
       ];
@@ -29,3 +30,3 @@ var tagParser = tagParserFactory(tagDefinitions);
       );
-        // Not that the description tag contains what appears to be another tag but it was not defined so
+        // Not that the description tag contains what appears to be another tag but it was ignored so
         // is consumed into the description tag!
@@ -32,0 +33,0 @@ expect(tags.tags[1]).toEqual(

jsdoc/spec/processors/compute-path.spec.js

@@ -10,2 +10,3 @@ var processor = require('../../processors/compute-path');
     config = _.extend(Config);
+    config.set('rendering.contentsFolder', 'partials');
     processor.init(config);
@@ -27,5 +28,5 @@ });
     expect(doc1.path).toEqual('a/b/c/foo');
-    expect(doc1.outputPath).toEqual('contents/a/b/c/foo.html');
+    expect(doc1.outputPath).toEqual('partials/a/b/c/foo.html');
     expect(doc2.path).toEqual('x/y/z');
-    expect(doc2.outputPath).toEqual('contents/x/y/z.html');
+    expect(doc2.outputPath).toEqual('partials/x/y/z.html');
   });
@@ -43,3 +44,3 @@
     expect(doc.path).toEqual('a/b/c');
-    expect(doc.outputPath).toEqual('contents/a/b/c.html');
+    expect(doc.outputPath).toEqual('partials/a/b/c.html');
   });
@@ -61,13 +62,2 @@
 
-  it("should prepend the configured contents folder to the outputPath", function() {
-    var doc = {
-      file: 'x/y/z/foo.bar',
-      fileName: 'foo'
-    };
-    config.set('rendering.contentsFolder', 'different/path');
-    processor.init(config);
-    processor.process([doc]);
-
-    expect(doc.outputPath).toEqual('different/path/x/y/z/foo.html');
-  });
 });

jsdoc/tag-defs/index.js

@@ -7,4 +7,3 @@ var checkProperty = require('dgeni/lib/utils/check-property');
   {
-    name: 'name',
-    required: true
+    name: 'name'
   },
@@ -68,2 +67,4 @@
   { name: 'description' },
+  { name: 'private' },
+  { name: 'see'},
   { name: 'usage' },
@@ -70,0 +71,0 @@ { name: 'animations' },

ngdoc/index.js

@@ -23,2 +23,3 @@ var path = require('canonical-path');
     require('./processors/filter-ngdocs'),
+    require('./processors/compute-id'),
     require('./processors/api-docs'),
@@ -25,0 +26,0 @@ require('./processors/component-groups-generate')

ngdoc/inline-tag-defs/link.js

@@ -13,3 +13,3 @@ var INLINE_LINK = /(\S+)(?:\s+(.+))?/;
 
-        var linkInfo = partialNames.getLink(uri, title);
+        var linkInfo = partialNames.getLink(uri, title, doc);
 
@@ -16,0 +16,0 @@ if ( !linkInfo.valid ) {

ngdoc/processors/api-docs.js

 var _ = require('lodash');
 var log = require('winston');
+var path = require('canonical-path');
+var partialsPath;
 
@@ -7,6 +9,10 @@ module.exports = {
   description: 'Compute the various fields for docs in the API area',
-  runAfter: ['compute-id'],
+  runAfter: ['compute-id', 'partial-names'],
   runBefore: ['compute-path'],
   init: function(config, injectables) {
     injectables.value('moduleMap', Object.create(null));
+    partialsPath = config.get('rendering.contentsFolder');
+    if ( !partialsPath ) {
+      throw new Error('Invalid configuration. You must provide config.rendering.contentsFolder');
+    }
   },
@@ -23,3 +29,3 @@ process: function(docs, partialNames, moduleMap) {
 
-          doc.outputPath = _.template('${area}/${name}/index.html', doc);
+          doc.outputPath = path.join(partialsPath, _.template('${area}/${name}/index.html', doc));
           doc.path = _.template('${area}/${name}', doc);
@@ -51,3 +57,3 @@
 
-          doc.outputPath = _.template('${area}/${module}/${docType}/${name}.html', doc);
+          doc.outputPath = path.join(partialsPath, _.template('${area}/${module}/${docType}/${name}.html', doc));
           doc.path = _.template('${area}/${module}/${docType}/${name}', doc);
@@ -104,7 +110,12 @@ }
 
-        if ( serviceDoc ) {
+        if ( !serviceDoc ) {
+          log.warn('Missing service "' + serviceId + '" for provider "' + doc.id + '"');
+        } else if ( _.isArray(serviceDoc) ) {
+          log.warn('Ambiguous service name "' + serviceId + '" for provider "' + doc.id + '"\n' +
+            _.reduce(doc, function(msg, doc) {
+              return msg + '\n  "' + doc.id + '"';
+            }, 'Matching docs: '));
+        } else {
           doc.serviceDoc = serviceDoc;
           serviceDoc.providerDoc = doc;
-        } else {
-          log.warn('Missing service "' + serviceId + '" for provider "' + doc.id + '"');
         }
@@ -111,0 +122,0 @@ }

ngdoc/processors/component-groups-generate.js

 var _ = require('lodash');
+var path = require('canonical-path');
+var partialsPath;
 
@@ -6,4 +8,10 @@ module.exports = {
   description: 'Add new component-groups docs',
-  runAfter: ['adding-extra-docs'],
+  runAfter: ['adding-extra-docs', 'api-docs'],
   runBefore: ['extra-docs-added'],
+  init: function(config) {
+    partialsPath = config.get('rendering.contentsFolder');
+    if ( !partialsPath ) {
+      throw new Error('Invalid configuration. You must provide config.rendering.contentsFolder');
+    }
+  },
   process: function(docs, moduleMap) {
@@ -27,3 +35,3 @@ _.forEach(moduleMap, function(module) {
             components: docs,
-            outputPath: _.template('partials/${module.area}/${module.name}/${docType}/index.html', { module: module, docType: docType }),
+            outputPath: path.join(partialsPath, _.template('${module.area}/${module.name}/${docType}/index.html', { module: module, docType: docType })),
             path: _.template('${module.area}/${module.name}/${docType}', { module: module, docType: docType })
@@ -30,0 +38,0 @@ };

ngdoc/processors/compute-id.js

@@ -22,9 +22,9 @@ var _ = require('lodash');
 
-      } else if (doc.docType === 'error') {
-
-        doc.id = doc.name;
-
       } else {
 
-        doc.id = doc.fileName;
+        if (doc.docType === 'error') {
+          doc.id = doc.name;
+        } else {
+          doc.id = doc.fileName;
+        }
 
@@ -31,0 +31,0 @@ }

ngdoc/processors/filter-ngdocs.js

@@ -7,2 +7,3 @@ var _ = require('lodash');
   runAfter: ['tags-parsed'],
+  runBefore: ['extracting-tags'],
   process: function(docs) {
@@ -9,0 +10,0 @@ var docCount = docs.length;

ngdoc/processors/partial-names.js

 var PartialNames = require('../utils/partial-names').PartialNames;
+var _ = require('lodash');
 
 module.exports = {
   name: 'partial-names',
-  runBefore: ['loading-files'],
+  description: 'Add all the docs to the partialNames store',
+  runAfter: ['compute-id'],
   init: function(config, injectables) {
     injectables.value('partialNames', new PartialNames());
+  },
+  process: function(docs, partialNames) {
+    _.forEach(docs, function(doc) {
+      partialNames.addDoc(doc);
+    });
   }
 };

ngdoc/spec/inline-tag-defs/link.spec.js

@@ -18,7 +18,5 @@ var _ = require('lodash');
 
-    partialNames = new PartialNames();
-    partialNames.addDoc({ id: 'module:ng.directive:ngInclude', path: 'api/ng/directive/ngInclude', name: 'ngInclude' });
-
     doc = {
-      id: 'test.doc',
+      id: 'module:ng.directive:ngInclude',
+      path: 'api/ng/directive/ngInclude',
       componentType: 'directive',
@@ -35,2 +33,5 @@ module: 'ng',
 
+    partialNames = new PartialNames();
+    partialNames.addDoc(doc);
+
     linkHandler = linkTagDef.handlerFactory(partialNames);
@@ -52,9 +53,6 @@ });
   it("should check that any links in the links property of a doc reference a valid doc", function() {
-    expect(linkHandler(doc, 'link', 'module:ngOther.directive:ngDirective')).toEqual('<a href="module:ngOther.directive:ngDirective">module:ngOther.directive:ngDirective</a>');
-    expect(logger.warn).toHaveBeenCalled();
-    expect(logger.warn.calls[0].args).toEqual([
-      'Error processing link "module:ngOther.directive:ngDirective" for "test.doc" in file "some/file.js" at line 200:\n' +
-      'Invalid link (does not match any doc): "module:ngOther.directive:ngDirective"'
-    ]);
+    expect(function() {
+      linkHandler(doc, 'link', 'module:ngOther.directive:ngDirective');
+    }).toThrow('Invalid link (does not match any doc): "module:ngOther.directive:ngDirective"');
   });
 });

ngdoc/spec/processors/component-groups-generate.spec.js

@@ -1,2 +0,4 @@
-var plugin = require('../../processors/component-groups-generate');
+var _ = require('lodash');
+var processor = require('../../processors/component-groups-generate');
+var Config = require('dgeni/lib/utils/config').Config;
 
@@ -19,3 +21,6 @@ describe("component-groups processor", function() {
 
-    plugin.process(docs, modules);
+    config = _.extend(Config);
+    config.set('rendering.contentsFolder', 'partials');
+    processor.init(config);
+    processor.process(docs, modules);
 
@@ -22,0 +27,0 @@ expect(docs.length).toEqual(2);

ngdoc/spec/tag-defs/tags.spec.js

@@ -128,34 +128,3 @@ var _ = require('lodash');
 
-  describe("id", function() {
 
-    describe("(for api docs)", function() {
-      it("should compute the id from other properties", function() {
-        var doc = {
-          docType: 'service',
-          name: '$http',
-          area: 'api',
-          module: 'ngRoute'
-        };
-        expect(doDefault(doc, 'id')).toEqual('module:ngRoute.service:$http');
-      });
-
-      it("should extract the container and member from the name if it is a memberOf type", function() {
-        var doc = {
-          docType: 'method',
-          name: '$http#get',
-          area: 'api',
-          module: 'ng'
-        };
-
-        expect(doDefault(doc, 'id')).toEqual('$http#get');
-        expect(doc.name).toEqual('get');
-        expect(doc.memberof).toEqual('$http');
-        expect(doc.isMember).toEqual(true);
-      });
-
-    });
-  });
-
-
-
   describe("restrict", function() {
@@ -162,0 +131,0 @@

ngdoc/spec/utils/partial-names.spec.js

@@ -85,3 +85,26 @@ var util = require('../../utils/partial-names');
     });
+
+    it("should error if there are multiple docs with the same name", function() {
+      var partialNames = new util.PartialNames();
+      var doc1 = { id: 'module:ng.directive:ngClick', name: 'ngClick', path: 'api/ng/directive/ngClick' };
+      var doc2 = { id: 'module:ngTouch.directive:ngClick', name: 'ngClick', path: 'api/ngTouch/directive/ngClick' };
+      partialNames.addDoc(doc1);
+      partialNames.addDoc(doc2);
+      expect(partialNames.getLink('ngClick').error).toMatch(/Ambiguous link:/);
+    });
+
+    it("should filter ambiguous documents by area before failing", function() {
+      var partialNames = new util.PartialNames();
+      var doc1 = { id: 'module:ng.directive:ngClick', name: 'ngClick', path: 'api/ng/directive/ngClick', area: 'api' };
+      var doc2 = { id: 'ngClick', name: 'ngClick', path: 'guide/ngClick', area: 'guide' };
+      partialNames.addDoc(doc1);
+      partialNames.addDoc(doc2);
+      expect(partialNames.getLink('ngClick', 'ngClick Guide', doc2)).toEqual({
+        type: 'doc',
+        valid: true,
+        url: 'guide/ngClick',
+        title: 'ngClick Guide'
+      });
+    });
   });
 });

ngdoc/utils/partial-names.js

@@ -164,3 +164,3 @@ var _ = require('lodash');
  */
-PartialNames.prototype.getLink = function(url, title) {
+PartialNames.prototype.getLink = function(url, title, currentDoc) {
   var linkInfo = {
@@ -179,2 +179,13 @@ url: url,
 
+  if ( _.isArray(doc) && currentDoc ) {
+    // If there is more than one item with this name then first
+    // try to filter them by the currentDoc's area
+    doc = _.filter(doc, function(doc) {
+      return doc.area === currentDoc.area;
+    });
+    if ( doc.length === 1 ) {
+      doc = doc[0];
+    }
+  }
+
   if ( _.isArray(doc) ) {
@@ -181,0 +192,0 @@

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A collection of dgeni packages for generating documentation from source code",
@@ -5,0 +5,0 @@ "scripts": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

168323

increased by3.17%

Number of package files

120

increased by1.69%

Lines of code

3780

increased by2.94%

No dependency changes