dgeni-packages - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

CHANGELOG.md

@@ -1,5 +0,16 @@
-## 0.4.0 03/06/2014
+## v0.5.0 03/07/2014
 
 **New Features**
 
+* feat(jsdoc extractor): add next code node to the doc  22a59651
+
+**Bug Fixes**
+
+* fix(jsdoc extractor): ignore non-jsdoc comments  50ad83d8
+* fix(inline link tag): throw error if link is invalid   07af2f42
+
+## v0.4.0 03/06/2014
+
+**New Features**
+
 * feat(examples): move injected example into a template  cc658f31
@@ -26,3 +37,3 @@ * feat(jsdoc): add `rendering.nunjucks.config` field to config  eb805097
 
-## 0.3.1 03/02/2014
+## v0.3.1 03/02/2014
 
@@ -34,3 +45,3 @@ **Bug Fixes**
 
-## 0.3.0 02/28/2014
+## v0.3.0 02/28/2014
 
@@ -56,3 +67,3 @@ **New Features**
 
-## 0.2.4 02/25/2014
+## v0.2.4 02/25/2014
 
@@ -63,3 +74,3 @@ **Bug Fixes**
 
-## 0.2.3 02/25/2014
+## v0.2.3 02/25/2014
 
@@ -77,3 +88,3 @@ **Bug Fixes**
 
-## 0.2.1 02/20/2014
+## v0.2.1 02/20/2014
 
@@ -84,3 +95,3 @@ **Bug Fixes**
 
-## 0.2.0 02/20/2014
+## v0.2.0 02/20/2014
 
@@ -91,3 +102,3 @@ **New Features**
 
-## 0.1.0 02/20/2014
+## v0.1.0 02/20/2014
 
@@ -94,0 +105,0 @@ **Bug Fixes**

jsdoc/extractors/jsdoc.js

 var _ = require('lodash');
 var jsParser = require('esprima');
+var walk = require('../lib/walk');
 var LEADING_STAR = /^\s*\*[^\S\n]?/gm;
@@ -9,8 +10,18 @@
 
-    var docFromComment = function(comment) {
+    var ast = jsParser.parse(contents, {
+      loc: true,
+      range: true,
+      comment: true
+    });
 
-      if ( comment.type === 'Block' && comment.value.charAt(0) === '*' ) {
-        // We have a jsdoc comment (i.e. starting with /** ) - the parser strips off the first "/*"
-        // so we are just left with a single asterisk
-        
+    return _(ast.comments)
+
+      .filter(function(comment) {
+        // To test for a jsdoc comment (i.e. starting with /** ), we need to check for a leading
+        // star since the parser strips off the first "/*"        
+        return comment.type === 'Block' && comment.value.charAt(0) === '*';
+      })
+
+      .map(function(comment) {
+
         // Strip off any leading stars
@@ -22,2 +33,3 @@ text = comment.value.replace(LEADING_STAR, '');
 
+        // Create a doc from this comment
         return {
@@ -29,14 +41,10 @@ fileType: 'js',
           basePath: basePath,
-          content: text
+          content: text,
+          code: walk.findNodeAfter(ast, comment.range[1]+1)
         };
-      }
-    };
 
-    var ast = jsParser.parse(contents, {
-      loc: true,
-      comment: true
-    });
+      })
 
-    return _.map(ast.comments, docFromComment);
+      .value();
   }
 };

jsdoc/processors/inline-tags.js

@@ -76,3 +76,8 @@ var _ = require('lodash');
             } catch(e) {
-              log.error('Error running inline tag handler for inline tag "' + match + '" for "' + doc.id + '" in file "' + doc.file + '" at line ' + doc.startingLine + '\n' + e.stack);
+              throw new Error('There was a problem running the @' + tagName +
+                          ' inline tag handler for ' + match + '\n' +
+                          'Doc: ' + doc.id + '\n' +
+                          'File: ' + doc.file + '\n' +
+                          'Line: ' + doc.startingLine + '\n' +
+                          'Message: \n' + e.message);
             }
@@ -79,0 +84,0 @@

jsdoc/spec/extractors/jsdoc.spec.js

@@ -1,2 +0,2 @@
-var jsExtractor = require('../../extractors/jsdoc');
+var extractor = require('../../extractors/jsdoc');
 
@@ -9,4 +9,4 @@ var srcJsContent = require('./_test-data/srcJsFile.js');
     it("should only match js files", function() {
-      expect(jsExtractor.pattern.test('abc.js')).toBeTruthy();
-      expect(jsExtractor.pattern.test('abc.ngdoc')).toBeFalsy();
+      expect(extractor.pattern.test('abc.js')).toBeTruthy();
+      expect(extractor.pattern.test('abc.ngdoc')).toBeFalsy();
     });
@@ -16,4 +16,4 @@ });
     it('should return a collection of documents extracted from the file', function() {
-      var docs = jsExtractor.processFile('some/file.js', srcJsContent);
-      docs.length = 3;
+      var docs = extractor.processFile('some/file.js', srcJsContent);
+      expect(docs.length).toEqual(3);
       expect(docs[0]).toEqual(jasmine.objectContaining(docsFromJsContent[0]));
@@ -23,3 +23,16 @@ expect(docs[1]).toEqual(jasmine.objectContaining(docsFromJsContent[1]));
     });
+
+    it("should ignore non-jsdoc comments", function() {
+      var docs = extractor.processFile('some/file.js', '/** Some jsdoc comment */\n// A line comment\n\/* A non-jsdoc block comment*/');
+      expect(docs.length).toEqual(1);
+    });
+
+    it("should find the next code item following the comment and attach it to the doc", function() {
+      var docs = extractor.processFile('some/file.js', srcJsContent);
+      expect(docs.length).toEqual(3);
+      expect(docs[0].code.node.type).toEqual('FunctionDeclaration');
+      expect(docs[1].code.node.type).toEqual('ExpressionStatement');
+      expect(docs[2].code.node.type).toEqual('ReturnStatement');
+    });
   });
 });

ngdoc/inline-tag-defs/link.js

@@ -1,3 +0,1 @@
-var _ = require('lodash');
-var log = require('winston');
 var INLINE_LINK = /(\S+)(?:\s+(.+))?/;
@@ -18,10 +16,6 @@
         if ( !linkInfo.valid ) {
-          log.warn('Error processing link "' + uri + '" for "' + doc.id + '" in file "' + doc.file + '" at line ' + doc.startingLine + ':\n' + linkInfo.error);
-          linkInfo = {
-            url: uri,
-            title: title || uri
-          };
+          throw new Error(linkInfo.error);
         }
         
-        return _.template('<a href="${url}">${title}</a>', linkInfo);
+        return '<a href="' + linkInfo.url + '">' + linkInfo.title + '</a>';
       });
@@ -28,0 +22,0 @@ };

ngdoc/processors/api-docs.js

@@ -7,3 +7,4 @@ var _ = require('lodash');
   description: 'Compute the various fields for docs in the API area',
-  runAfter: ['tags-extracted'],
+  runAfter: ['compute-id'],
+  runBefore: ['compute-path'],
   init: function(config, injectables) {
@@ -13,26 +14,43 @@ injectables.value('moduleMap', Object.create(null));
   process: function(docs, partialNames, moduleMap) {
+    var parts;
 
-    // Identify the modules and add some meta data to each
+    // Compute some extra fields for docs in the API area
     _.forEach(docs, function(doc) {
-      if ( doc.docType === 'module' ) {
 
-        moduleMap[doc.name] = doc;
+      if ( doc.area === 'api' && doc.docType !== 'overview' ) {
 
-        // Create a place to store references to the module's components
-        doc.components = [];
+        if ( doc.docType === 'module' ) {
 
-        // Compute the package name and filename for the module
-        var match = /^ng(.*)/.exec(doc.name);
-        if ( match ) {
-          var packageName = match[1].toLowerCase();
-          if ( packageName ) { packageName = '-' + packageName; }
-          doc.packageName = 'angular' + packageName;
-          doc.packageFile = doc.packageName + '.js';
+          doc.outputPath = _.template('${area}/${name}/index.html', doc);
+          doc.path = _.template('${area}/${name}', doc);
+
+          moduleMap[doc.name] = doc;
+
+          // Create a place to store references to the module's components
+          doc.components = [];
+
+          // Compute the package name and filename for the module
+          var match = /^ng(.*)/.exec(doc.name);
+          if ( match ) {
+            var packageName = match[1].toLowerCase();
+            if ( packageName ) { packageName = '-' + packageName; }
+            doc.packageName = 'angular' + packageName;
+            doc.packageFile = doc.packageName + '.js';
+          }
+
+        } else {
+
+          // Is this doc a member of another doc?
+          if ( doc.name.indexOf('#' ) !== -1 ) {
+            doc.isMember = true;
+            parts = doc.id.split('#');
+            doc.memberof = parts[0];
+            doc.name = parts[1];
+          }
+
+          doc.outputPath = _.template('${area}/${module}/${docType}/${name}.html', doc);
+          doc.path = _.template('${area}/${module}/${docType}/${name}', doc);
         }
       }
 
-      // Only track this doc if it is not going to be merged as a member of another doc
-      if ( !doc.isMember ) {
-        partialNames.addDoc(doc);
-      }
     });
@@ -39,0 +57,0 @@

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

 var util = require('../../utils/partial-names');
 
-describe("partial-name", function() {
+describe("PartialNames", function() {
 
-  describe("PartialNames", function() {
+  describe("addDoc", function() {
     it("should return an array of partial names for a full code name", function() {
@@ -20,35 +20,68 @@ var partialNames = new util.PartialNames();
     });
+  });
 
+  describe("removeDoc", function() {
+    it("should remove the doc from any parts of the partial name map", function() {
+      var partialNames = new util.PartialNames();
+      var doc1 = { id: 'module:ng.service:$log' };
+      var doc2 = { id: 'module:ngMock.service:$log' };
+      partialNames.addDoc(doc1);
+      partialNames.addDoc(doc2);
 
-    describe("getLink", function() {
-      it("should lookup urls against the docs", function() {
-        var partialNames = new util.PartialNames();
-        var doc = { id: 'module:ng.directive:ngClick', name: 'ngClick', path: 'api/ng/directive/ngClick' };
-        partialNames.addDoc(doc);
+      expect(partialNames.map).toEqual({
+        '$log': [doc1, doc2],
+        'service:$log': [doc1, doc2],
+        'ng.$log': doc1,
+        'ngMock.$log': doc2,
+        'module:ng.$log': doc1,
+        'module:ngMock.$log': doc2,
+        'ng.service:$log': doc1,
+        'ngMock.service:$log': doc2,
+        'module:ng.service:$log': doc1,
+        'module:ngMock.service:$log': doc2,
+      });
 
-        expect(partialNames.getLink('ngClick')).toEqual({
-          type: 'doc',
-          valid: true,
-          url: 'api/ng/directive/ngClick',
-          title: '<code>ngClick</code>'
-        });
+      partialNames.removeDoc(doc1);
 
-        expect(partialNames.getLink('ngClick', 'Click Event')).toEqual({
-          type: 'doc',
-          valid: true,
-          url: 'api/ng/directive/ngClick',
-          title: 'Click Event'
-        });
+      expect(partialNames.map).toEqual({
+        '$log': doc2,
+        'service:$log': doc2,
+        'ngMock.$log': doc2,
+        'module:ngMock.$log': doc2,
+        'ngMock.service:$log': doc2,
+        'module:ngMock.service:$log': doc2,
+      });
+    });
+  });
 
-        expect(partialNames.getLink('ngClick#some-header', 'Click Event')).toEqual({
-          type: 'doc',
-          valid: true,
-          url: 'api/ng/directive/ngClick#some-header',
-          title: 'Click Event'
-        });
 
+  describe("getLink", function() {
+    it("should lookup urls against the docs", function() {
+      var partialNames = new util.PartialNames();
+      var doc = { id: 'module:ng.directive:ngClick', name: 'ngClick', path: 'api/ng/directive/ngClick' };
+      partialNames.addDoc(doc);
+
+      expect(partialNames.getLink('ngClick')).toEqual({
+        type: 'doc',
+        valid: true,
+        url: 'api/ng/directive/ngClick',
+        title: '<code>ngClick</code>'
       });
+
+      expect(partialNames.getLink('ngClick', 'Click Event')).toEqual({
+        type: 'doc',
+        valid: true,
+        url: 'api/ng/directive/ngClick',
+        title: 'Click Event'
+      });
+
+      expect(partialNames.getLink('ngClick#some-header', 'Click Event')).toEqual({
+        type: 'doc',
+        valid: true,
+        url: 'api/ng/directive/ngClick#some-header',
+        title: 'Click Event'
+      });
+
     });
   });
-
 });

ngdoc/tag-defs/index.js

@@ -54,52 +54,5 @@ var checkProperty = require('dgeni/lib/utils/check-property');
 
-  {
-    name: 'id',
-    defaultFn: function(doc) {
-      var parts, partialFolder = 'partials';
-      if ( doc.area === 'api' && doc.docType !== 'overview' ) {
-        if ( doc.docType === 'module' ) {
-          doc.id = _.template('module:${name}', doc);
-          doc.outputPath = _.template('${area}/${name}/index.html', doc);
-          doc.path = _.template('${area}/${name}', doc);
+  { name: 'id' },
 
-        } else if ( doc.name.indexOf('#' ) === -1 ) {
-          doc.id = _.template('module:${module}.${docType}:${name}', doc);
-          doc.outputPath = _.template('${area}/${module}/${docType}/${name}.html', doc);
-          doc.path = _.template('${area}/${module}/${docType}/${name}', doc);
 
-        } else {
-          doc.id = doc.name;
-          doc.isMember = true;
-          parts = doc.id.split('#');
-          doc.memberof = parts[0];
-          doc.name = parts[1];
-          // This is a member of another doc so it doesn't need an output path
-        }
-      } else {
-        doc.id = doc.fileName;
-
-        if ( doc.docType === 'error' ) {
-          // Parse out the error info from the id
-          doc.id = doc.name;
-          parts = doc.id.split(':');
-          doc.namespace = parts[0];
-          doc.name = parts[1];
-        }
-
-        doc.path = path.join(path.dirname(doc.file));
-        if ( doc.fileName !== 'index' ) {
-          doc.path += '/' + doc.fileName;
-        }
-        doc.outputPath = doc.path + '.html';
-      }
-
-      if ( doc.outputPath ) {
-        doc.outputPath = partialFolder + '/' + doc.outputPath;
-      }
-      
-      return doc.id;
-    }
-  },
-
-
   {
@@ -106,0 +59,0 @@ name: 'restrict',

ngdoc/utils/partial-names.js

@@ -128,2 +128,28 @@ var _ = require('lodash');
 
+PartialNames.prototype.removeDoc = function(doc) {
+
+  var map = this.map;
+
+  _.forEach(doc.partialNames, function(partialName) {
+
+    var matchedDocs = map[partialName];
+    
+    if ( matchedDocs === doc ) {
+      // There is only one doc and it is the one we want to remove
+      delete map[partialName];
+    } else if ( _.isArray(matchedDocs) ) {
+      // We have an array of docs so we need to remove the culprit
+      var index = matchedDocs.indexOf(doc);
+      if ( index !== -1 ) {
+        matchedDocs.splice(index, 1);
+      }
+      if ( matchedDocs.length === 1 ) {
+        map[partialName] = matchedDocs[0];
+      }
+    }
+
+  });
+};
+
+
 PartialNames.prototype.getDoc = function(partialName) {
@@ -130,0 +156,0 @@ return this.map[partialName];

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.4.0",
+  "version": "0.5.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

163155

increased by11.9%

Number of package files

118

increased by4.42%

Lines of code

3672

increased by14.75%

No dependency changes