dgeni-packages - npm Package Compare versions

Comparing version 0.10.0-rc.2 to 0.10.0-rc.3

base/processors/read-files.js

@@ -144,3 +144,3 @@ var path = require('canonical-path');
     sourceInfo = { include: sourceInfo };
-  } else if ( !_.isObject(sourceInfo) ) {
+  } else if ( !_.isObject(sourceInfo) || !sourceInfo.include) {
 
@@ -147,0 +147,0 @@ throw new Error('Invalid sourceFiles parameter. ' +

base/processors/read-files.spec.js

@@ -16,4 +16,4 @@ var path = require('canonical-path');
 
-    var dgeni = new Dgeni([mockPackage()]);
-    var injector = dgeni.configureInjector();
+  var dgeni = new Dgeni([mockPackage()]);
+  var injector = dgeni.configureInjector();
 
@@ -82,2 +82,36 @@ var processor = injector.get('readFilesProcessor');
 
+
+  it("should complain if there is no matching file-reader", function(done) {
+      var mockFileReader = {
+        name: 'mockFileReader',
+        defaultPattern: /\.js$/,
+        getDocs: function(fileInfo) { return [{ fileInfo2: fileInfo }]; }
+      };
+
+      processor = createReadFilesProcessor([mockFileReader], ['docs/*'], '../fixtures');
+      processor.$process().then(function(docs) {
+        console.log('expected createReadFileProcessor to fail');
+        expect(docs).toBeUndefined();
+      }, function(err) {
+        expect(err).toMatch('No file reader found for .+b\\.ngdoc');
+        done();
+      });
+  });
+
+
+  it("should complain if the sourceFiles property is not valid", function() {
+    expect(function() {
+      var mockFileReader = {
+        name: 'mockFileReader',
+        defaultPattern: /\.js$/,
+        getDocs: function(fileInfo) { return [{ fileInfo2: fileInfo }]; }
+      };
+      var processor = createReadFilesProcessor([ mockFileReader ], [ { wrong: 'docs/*'} ], '../fixtures');
+      processor.$process();
+    }).toThrowError('Invalid sourceFiles parameter. ' +
+      'You must pass an array of items, each of which is either a string or an object of the form ' +
+      '{ include: "...", basePath: "...", exclude: "...", fileReader: "..." }');
+  });
+
+
   describe('fileReaders', function() {
@@ -84,0 +118,0 @@

base/processors/write-files.spec.js

@@ -8,4 +8,8 @@ var path = require('canonical-path');
 describe("writeFilesProcessor", function() {
-  it("should write each document to a file", function() {
-    var writeFileSpy = jasmine.createSpy('writeFile').and.returnValue(Q());
+  var processor, writeFileSpy, mockLog;
+
+
+  beforeEach(function() {
+    writeFileSpy = jasmine.createSpy('writeFile').and.returnValue(Q());
+
     var testPackage = mockPackage().factory('writeFile', function() { return writeFileSpy; });
@@ -19,7 +23,17 @@
 
-    var processor = injector.get('writeFilesProcessor');
+    processor = injector.get('writeFilesProcessor');
     processor.outputFolder = 'build';
+
+    mockLog = injector.get('log');
+  });
+
+  it("should write each document to a file", function() {
     processor.$process([{ renderedContent: 'SOME RENDERED CONTENT', outputPath: 'doc/path.html' }]);
     expect(writeFileSpy).toHaveBeenCalledWith(path.resolve('some/path/build/doc/path.html'), 'SOME RENDERED CONTENT');
   });
+
+  it("should log a debug message if a doc has no outputPath", function() {
+    processor.$process([{ renderedContent: 'SOME RENDERED CONTENT', id: 'doc1', docType: 'test' }]);
+    expect(mockLog.debug).toHaveBeenCalledWith('Document "doc1, test" has no outputPath.');
+  });
 });

CHANGELOG.md

 # Changelog
 
 
+## v0.10.0-rc.3 11th September 2014
+
+Fixes:
+
+* feat(ngdoc/providerDocsProcessor): add missing processor     2ea87c15
+* fix(ngdoc/moduleDocsProcessor): add missing var declaration    196c1758
+
+Testing Improvements
+
+* test(ngdoc/getLinkInfo): test missing and URL based links    4170e83f
+* refact(ngdoc/moduleDocsProcessor): improve and test error messages     d749563f
+* test(base/writeFilesProcessor): test corner cases     fef7a919
+* test(nunjucks/filters): add missing tests     13dc8a77
+* test(jsdoc/extractTagsProcessor): test corner cases     b8157723
+* test(base/readFilesProcessor): add corner case tests      17765d52
+
 ## v0.10.0-rc.2 10th September 2014
@@ -5,0 +21,0 @@

jsdoc/processors/extract-tags.spec.js

@@ -23,3 +23,3 @@ var mockPackage = require('../mocks/mockPackage');
 
-  var parseTagsProcessor, processor;
+  var parseTagsProcessor, processor, mockLog;
 
@@ -31,4 +31,25 @@ beforeEach(function() {
     processor = injector.get('extractTagsProcessor');
+    mockLog = injector.get('log');
   });
 
+  it("should log a warning if the doc contains bad tags", function() {
+
+      var doc = createDoc([]);
+      doc.tags.badTags = [ {
+        name: 'bad1',
+        description: 'bad tag 1',
+        typeExpression: 'string',
+        errors: [
+          'first bad thing',
+          'second bad thing'
+        ]
+      }];
+
+      processor.$process([doc]);
+      expect(mockLog.warn).toHaveBeenCalledWith('Invalid tags found - doc\n' +
+        'Line: undefined: @undefined {string} bad1 bad tag 1...\n' +
+        '    * first bad thing\n' +
+        '    * second bad thing\n\n');
+  });
+
   describe('default tag-def', function() {
@@ -35,0 +56,0 @@ it("should the extract the description property to a property with the name of the tagDef", function() {

ngdoc/index.js

@@ -18,2 +18,3 @@ var path = require('canonical-path');
 .processor(require('./processors/moduleDocs'))
+.processor(require('./processors/providerDocs'))
 
@@ -20,0 +21,0 @@

ngdoc/processors/moduleDocs.js

@@ -54,7 +54,8 @@ var _ = require('lodash');
           } else if ( matchingModules.length > 1 ) {
-            console.log(matchingModules.length);
+            var error = createDocMessage('Ambiguous module reference: "' + doc.module + '"', doc);
+            error += '\nMatching modules:\n';
             _.forEach(matchingModules, function(mod) {
-              console.log(mod.id);
+              error += '- ' + mod.id + '\n';
             });
-            throw new Error(createDocMessage('Ambiguous module reference: "' + doc.module + '"', doc));
+            throw new Error(error);
           }
@@ -61,0 +62,0 @@ }

ngdoc/processors/moduleDocs.spec.js

@@ -5,3 +5,3 @@ var mockPackage = require('../mocks/mockPackage');
 describe("moduleDocsProcessor", function() {
-  var processor, aliasMap;
+  var processor, aliasMap, moduleMap;
 
@@ -16,2 +16,20 @@ beforeEach(function() {
 
+  it("should compute the package name and filename for the module", function() {
+    var doc1 = { docType: 'module', name: 'ng', id: 'module:ng' };
+    var doc2 = { docType: 'module', name: 'ngRoute', id: 'module:ngRoute' };
+    var doc3 = { docType: 'module', name: 'ngMock', id: 'module:ngMock', packageName: 'angular-mocks' };
+
+    processor.$process([doc1, doc2, doc3]);
+
+    expect(doc1.packageName).toEqual('angular');
+    expect(doc1.packageFile).toEqual('angular.js');
+
+    expect(doc2.packageName).toEqual('angular-route');
+    expect(doc2.packageFile).toEqual('angular-route.js');
+
+    expect(doc3.packageName).toEqual('angular-mocks');
+    expect(doc3.packageFile).toEqual('angular-mocks.js');
+
+  });
+
   it("should add module docs to the moduleMap", function() {
@@ -22,3 +40,3 @@ var doc1 = { docType: 'module', id: 'ng' };
 
-    processor.$process([doc1, doc2]);
+    processor.$process([doc1, doc2, doc3]);
 
@@ -50,2 +68,19 @@ expect(moduleMap.values().length).toEqual(2);
 
+  it("should complain if their is more than one matching modules", function() {
+    var doc1 = { docType: 'module', id: 'module:app.mod1', aliases: ['app', 'app.mod1', 'mod1', 'module:app', 'module:app.mod1', 'module:mod1'] };
+    var doc2 = { docType: 'module', id: 'module:app.mod2', aliases: ['app', 'app.mod2', 'mod2', 'module:app', 'module:app.mod2', 'module:mod2'] };
+    var doc3 = { docType: 'service', module: 'app', id: 'app.service' };
+
+    aliasMap.addDoc(doc1);
+    aliasMap.addDoc(doc2);
+
+    expect(function() {
+      processor.$process([doc1, doc2, doc3]);
+    }).toThrowError('Ambiguous module reference: "app" - doc "app.service" (service) \n'+
+                    'Matching modules:\n'+
+                    '- module:app.mod1\n'+
+                    '- module:app.mod2\n');
+
+  });
+
   it("should try using the module specifier if the module reference is ambiguous", function() {
@@ -52,0 +87,0 @@ var doc1 = { docType: 'module', id: 'module:ngMessages', aliases: ['ngMessages', 'module:ngMessages'] };

ngdoc/services/getLinkInfo.spec.js

@@ -56,2 +56,13 @@ var mockPackage = require('../mocks/mockPackage');
 
+  it("should error if no docs match the link", function() {
+    expect(getLinkInfo('ngClick').error).toEqual('Invalid link (does not match any doc): "ngClick"');
+  });
+
+  it("should not error if the link is a URL or starts with a hash", function() {
+    expect(getLinkInfo('some/path').error).toBeUndefined();
+    expect(getLinkInfo('some/path').title).toEqual('path');
+    expect(getLinkInfo('#fragment').error).toBeUndefined();
+    expect(getLinkInfo('#fragment').title).toEqual('fragment');
+  });
+
   it("should filter ambiguous documents by area before failing", function() {
@@ -58,0 +69,0 @@ var doc1 = { id: 'module:ng.directive:ngClick', name: 'ngClick', path: 'api/ng/directive/ngClick', area: 'api' };

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.10.0-rc.2",
+  "version": "0.10.0-rc.3",
   "description": "A collection of dgeni packages for generating documentation from source code",
@@ -32,2 +32,5 @@ "scripts": {
   },
+  "peerDependencies": {
+    "dgeni": "^0.4.0"
+  },
   "dependencies": {
@@ -57,10 +60,14 @@ "canonical-path": "0.0.2",
     "Peter Bacon Darwin <[e-mail]>",
+    "Stéphane Reynaud <[e-mail]>",
     "Andy Joslin <[e-mail]>",
+    "Pascal Precht <[e-mail]>",
     "Julie <[e-mail]>",
-    "Kevin Rowe <[e-mail]>",
-    "Pascal Precht <[e-mail]>",
-    "Konstantinos Rousis <[e-mail]>",
-    "Stéphane Reynaud <[e-mail]>",
-    "Matthew Harris <[e-mail]>"
+    "Jim Cummins <[e-mail]>",
+    "Andrew Joslin <[e-mail]>",
+    "thorn0 <[e-mail]>",
+    "kevinrowe <[e-mail]>",
+    "Pete Bacon Darwin <[e-mail]>",
+    "Matthew Harris <[e-mail]>",
+    "Konstantinos Rousis <[e-mail]>"
   ]
 }

README.md

 # Dgeni Packages
 
-This repository contains a collection of Dgeni packages that can be used by the Dgeni documentation
+This repository contains a collection of Dgeni **Packages** that can be used by the Dgeni documentation
 generator to create documentation from source code.
@@ -17,3 +17,3 @@
 * examples - Processors to support the runnable examples feature in the angular.js docs site.
-* dgeni - Support for documenting Dgeni packages
+* dgeni - Support for documenting Dgeni packages (**incomplete**)
 
@@ -24,7 +24,9 @@ ## `base` Package
 
+* `computeIdsProcessor` - Computes the `id` and `aliases` for documents using templates or helper
+functions, on a per docType basis.
+* `computePathsProcessor` - Computes the `path` and `outputPath` for documents using templates or helper
+functions, on a per docType basis.
 * `debugDumpProcessor` - dump the current state of the docs array to a file (disabled by default)
 * `readFilesProcessor` - used to load up documents from files.  This processor can be configured to use a
 set of **file readers**. There are file readers in the `jsdoc` and `ngdoc` packages.
-* `computePathsProcessor` - Computes the `path` and `outputPath` for documents using templates or helper
-functions, on a per docType basis.
 * `renderDocsProcessor` - render the documents into a property (`doc.renderedContent`) using a
@@ -38,2 +40,4 @@ `templateEngine`, which must be provided separately - see `nunjucks` package.
 
+* `aliasMap` - A map of ids/aliases to docs.  This is used for matching references to documents in
+links and relations such as modules and object members.
 * `createDocMessage` - a helper for creating nice messages about documents (useful in logging and
@@ -45,5 +49,8 @@ errors)
 of text.
+* `writeFile` - Write some contents to a file, ensuring the path to the file exists.
 
 
-The template used to render the doc is computed by the `templateFinder`, which uses the first match
+#### Template Finding
+
+The template used to render a doc is computed by the `templateFinder`, which uses the first match
 from a set of patterns in a set of folders, provided in the configuration. This allows a lot of control to provide
@@ -89,5 +96,5 @@ generic templates for most situations and specific templates for exceptional cases.
 file.
-* `parseTagsProcessor` - use a `tagParser` to parses the jsdoc tags in the document content.
 * `extractTagsProcessor` - use a `tagExtractor` to extract information from the parsed tags.
 * `inlineTagsProcessor` - Search the docs for inline tags that need to have content injected
+* `parseTagsProcessor` - use a `tagParser` to parses the jsdoc tags in the document content.
 
@@ -124,3 +131,5 @@ ### Tag Definitions
 
-The `ngdoc` Package depends upon the `jsdoc` and `nunjucks` packages.
+The `ngdoc` Package depends upon the `jsdoc` and `nunjucks` packages. It provides additional support for
+non-API documents written in files with `.ngdoc` extension; it also computes additional properties specific
+to Angular related code.
 
@@ -133,34 +142,18 @@ ## File Readers
 
-* `apiDocsProcessor` -
+* `filterNgdocsProcessor` -
+For AngularJS we are only interested in documents that contain the @ngdoc tag.  This processor
+removes docs that do not contain this tag.
 
-This processor runs computations that are specifically related to docs for API components. It does the following:
-
-  - Computes the package name for the module (eg angular or angular-sanitize)
-  - Collects up all documents that belong to the module
-  - Attaches them to the module doc in the `components` property
-  - Computes the URL path to the document in the docs app and the outputPath to the final output file
-  - It relates documents about angular services to their corresponding provider document.
-
-apiDocsProcessor has the following configuration options available (listed with the default values set):
-
-  ```js
-  apiDocsProcessor.apiDocsPath = undefined; // This is a required property that you must set
-  apiDocsProcessor.outputPathTemplate = '${area}/${module}/${docType}/${name}.html';
-  apiDocsProcessor.apiPathTemplate = '${area}/${module}/${docType}/${name}';
-  apiDocsProcessor.moduleOutputPathTemplate = '${area}/${name}/index.html';
-  apiDocsProcessor.modulePathTemplate = '${area}/${name}';
-  ```
-
 * `generateComponentGroupsProcessor` -
 Generate documents for each group of components (by type) within a module
 
-* `computeIdProcessor` -
-Compute the id property of the doc based on the tags and other meta-data
+* `memberDocsProcessor` - This processor connects docs that are members (properties, methods and events) to
+their container docs, removing them from the main docs collection.
 
-* `filterNgdocsProcessor` -
-For AngularJS we are only interested in documents that contain the @ngdoc tag.  This processor
-removes docs that do not contain this tag.
+* `moduleDocsProcessor` - This processor computes properties for module docs such as `packageName` and
+`packageFileName`; it adds modules to the `moduleMap` service and connects all the docs that are in a module
+to the module doc in the `components` property
 
-* `collectPartialNames` -
-Add all the docs to the `partialNameMap`
+* `providerDocsProcessor` - This processor relates documents about angular services to their corresponding
+provider document.
 
@@ -170,3 +163,5 @@
 
-This package modifies and adds new tag definitions on top of those provided by the `jsdoc` package.
+This package modifies and adds new tag definitions on top of those provided by the `jsdoc` package:
+`area`, `element`, `eventType`, `example`, `fullName`, `id`, `module`, `name`, `ngdoc`, packageName`,
+`parent`, `priority`, `restrict`, `scope` and `title`.
 
@@ -182,9 +177,7 @@
 
+* `getAliases()` - Get a list of all the aliases that can be made from the provided doc
+* `getDocFromAliases()` - Find a document from the `aliasMap` that matches the given alias
 * `getLinkInfo()` - Get link information to a document that matches the given url
-* `getPartialNames()` - Get a list of all the partial code names that can be made from the provided
-set of parts
 * `getTypeClass()` - Get a CSS class string for the given type string
-* `moduleMap` - A collection of modules keyed on the module name
-* `parseCodeName()` - Parse the code name into parts
-* `partialNameMap` - A map of partial names to docs
+* `moduleMap` - A collection of modules keyed on the module id
 
@@ -243,10 +236,9 @@
 
-* `parseExamplesProcessor` -
-Parse the `<example>` tags from the content and add them to the `examples` service
-* `generateExamplesProcessor` -
-Add new docs to the docs collection for each example in the `examples` service that will be rendered
-as files that can be run in the browser, for example as live in-place demos of the examples or for
-e2e testing.
+* `generateExamplesProcessor` - Add new docs to the docs collection for each example in the `examples` service
+that will be rendered as files that can be run in the browser, for example as live in-place demos of the
+examples or for e2e testing.
+* `parseExamplesProcessor` - Parse the `<example>` tags from the content and add them to the `examples` service
 * `generateProtractorTests` - Generate a protractor test files from the e2e tests in the examples
 
+
 ### Inline Tag Definitions
@@ -253,0 +245,0 @@

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

301181

increased by3.61%

Number of package files

220

increased by2.33%

Lines of code

5803

increased by3.72%

Worsened metrics

Dependency count

16

increased by6.67%

Number of lines in readme file

244

decreased by-3.17%

No dependency changes