dgeni-packages - npm Package Compare versions

Comparing version 0.9.0 to 0.9.1

CHANGELOG.md

@@ -0,1 +1,9 @@
+## v0.9.1 05/02/2014
+
+* fix(ngdoc/compute-path): use ngdoc specific version of this processor  3e17d31b
+* fix(code-name): cope with additional code situations   8b456b08
+* fix(jsdoc/trim-whitespace transform): only trim strings   5aa2376d
+* fix(jsdoc/jsdoc file-reader): cope with comments that have no code node   4e3857db
+* fix(code-name): recognise CallExpression nodes   14c5c103
+
 ## v0.9.0 05/01/2014
@@ -107,2 +115,10 @@
 
+## v0.8.3 04/23/2014
+
+**Bug Fixes**
+
+* fix(ngdoc): don't show first param in filter syntax   9c5a7f26
+* fix(jsdoc): fix typo in error message   b1e7dd08
+
+
 ## v0.8.2 03/22/2014
@@ -109,0 +125,0 @@

jsdoc/file-readers/jsdoc.js

@@ -34,3 +34,3 @@ var _ = require('lodash');
         var codeNode = walk.findNodeAfter(ast, comment.range[1]);
-        var codeAncestors = walk.ancestor(ast, codeNode.node);
+        var codeAncestors = codeNode && walk.ancestor(ast, codeNode.node);
 
@@ -37,0 +37,0 @@ // Create a doc from this comment

jsdoc/processors/code-name.js

@@ -14,3 +14,3 @@ var _ = require('lodash');
     _.forEach(docs, function(doc) {
-      doc.codeName = findCodeName(doc.codeNode.node);
+      doc.codeName = doc.codeNode && findCodeName(doc.codeNode.node);
     });
@@ -39,2 +39,4 @@ return docs;
       return findCodeName(node.property);
+    case 'CallExpression':
+      return findCodeName(node.callee);
     case 'Identifier':
@@ -48,2 +50,6 @@ return node.name;
       return null;
+    case 'ArrayExpression':
+      return null;
+    case 'Literal':
+      return node.value;
     case 'Program':
@@ -56,3 +62,3 @@ return node.body[0] ? findCodeName(node.body[0]) : null;
     default:
-      log.warn('HELP!');
+      log.warn('HELP! Unrecognised node type: ' + node.type);
       log.warn(node);
@@ -59,0 +65,0 @@ return null;

jsdoc/spec/file-readers/jsdoc.spec.js

@@ -47,2 +47,6 @@ var extractor = require('../../file-readers/jsdoc');
 
+    it("should not break if the comment has no code", function() {
+      extractor.processFile('some/file.js', 'function main() { } /** @some jsdoc comment */');
+    });
+
     it("should not remove windows new line characters when stripping stars from comments", function() {
@@ -49,0 +53,0 @@ var docs = extractor.processFile('some/file.js', '/** Some jsdoc comment\r\n* over multiple\r\n* lines\r\n**/');

jsdoc/spec/processors/code-name.spec.js

 var processor = require('../../processors/code-name');
+var jsParser = require('esprima');
 
 describe('code-name doc processor', function() {
+  it("should understand CallExpressions", function() {
+    var ast = jsParser.parse('(function foo() { })()');
+    var doc = { codeNode: { node: ast } };
+    processor.process([doc]);
+    expect(doc.codeName).toEqual('foo');
+  });
 
+  it("should understand ArrayExpressions", function() {
+    var ast = jsParser.parse("$CompileProvider.$inject = ['$provide', '$$sanitizeUriProvider'];");
+    var doc = { codeNode: { node: ast } };
+    processor.process([doc]);
+    expect(doc.codeName).toEqual('$inject');
+  });
+
 });

jsdoc/spec/tag-defs/transforms/trim-whitespace.spec.js

@@ -9,2 +9,7 @@ var transform = require('../../../tag-defs/transforms/trim-whitespace');
 
+  it("should not do anything if the value is not a string", function() {
+    var someNonStringObject = {};
+    expect(transform({}, {}, someNonStringObject)).toEqual(someNonStringObject);
+  });
+
 });

jsdoc/tag-defs/transforms/trim-whitespace.js

@@ -0,1 +1,3 @@
+var _ = require('lodash');
+
 /**
@@ -5,3 +7,6 @@ * Trim excess whitespace from the value
 module.exports = function(doc, tag, value) {
-  return value.trim();
+  if ( _.isString(value) ) {
+    return value.trim();
+  }
+  return value;
 };

ngdoc/index.js

@@ -0,1 +1,2 @@
+var _ = require('lodash');
 var path = require('canonical-path');
@@ -21,3 +22,10 @@ var packagePath = __dirname;
 
+  // Replace the default compute-path processor
+  var processors = config.get('processing.processors');
+  _.remove(processors, {name: 'compute-path'});
   config.append('processing.processors', [
+    require('./processors/compute-path')
+  ]);
+
+  config.append('processing.processors', [
     require('./processors/partial-names'),
@@ -24,0 +32,0 @@ require('./processors/filter-ngdocs'),

package.json

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

README.md

@@ -9,48 +9,74 @@ # Dgeni Packages
 
-* `jsdoc` - a standard set of processors that can extract jsdoc documents and render them as HTML.
-* `ngdoc` - *(depends upon the `jsdoc` package)* an extra set of processors and templates that
-are specific to angularjs projects.
+* base - The minimal set of processors to get started with Dgeni
+* jsdoc - Tag parsing and extracting
+* nunjucks - The nunjucks template rendering engine. No longer in jsdoc - you must add this
+  explicitly to your config or you will get
+  `Error: No provider for "templateEngine"! (Resolving: templateEngine)`
+* ngdoc - The angular.js specific tag-defs, processors and templates.  This loads the jsdoc and
+  nunjucks packages for you.
+* examples - Processors to support the runnable examples feature in the angular.js docs site.
 
+#### `base` Package
 
+This package contains the following processors:
+
+* `read-files` - 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.
+* `render-docs` - render the documents into a property (`doc.renderedContent`) using a
+`templateEngine`, which must be provided separately - see `nunjucks` package.
+* `templateFinder` - search folders using patterns to find a template that matches a given document.
+* `unescape-comments` - unescape comment markers that would break the jsdoc comment style,
+e.g. `*/`
+* `write-files` - write the docs to disk
+
+#### `nunjucks` Package
+
+This package provides a nunjucks driven implementation of the `templateEngine` required by the
+`base` package `render-docs` processor.
+
+* `nunjucks-template-engine` - provide a `templateEngine` that uses the Nunjucks template library
+to render the documents into text, such as HTML or JS, based on templates.
+
 #### `jsdoc` Package
 
+This package contains the following file-readers:
+
+* `jsdoc` - can read documents from jsdoc style comments in source code files.
+
 This package contains the following processors:
 
-* `doc-extractor` - used to load up documents from files.  This processor can be configured to use a
-set of **extractors**.  The `jsdoc` package has a single `js` extractor, which can extract documents
-from jsdoc style comments in files.
-* `tag-parser` - parses the jsdoc tags in the extracted documents.
-* `tag-extractor` - extracts the tags information and converts it to specific properties on
-the documents, based on a set of tag-definitions.  The `jsdoc` package contains definitions for the
-following tags: `name`, `memberof`, `param`, `property`, `returns`, `module`, `description`, `usage`,
-`animations`, `constructor`, `class`, `classdesc`, `global`, `namespace`, `method`, `type` and `kind`.
-* `nunjucks-renderer` - uses the Nunjucks template library to render the documents into files, such
-as HTML or JS, based on templates.
+* `code-name` - infer the name of the document from the code following the document in the source
+file.
+* `compute-path` - infer the path to the document, used for writing the file and for navigation
+to the document in a web app.
+* `defaultTagTransforms` - provide a collection of tag transform functions to apply to every tag.
+See the transforms in the `tagExtractor` processor.
+* `parse-tags` - use a `tagParser` to parses the jsdoc tags in the document content.
+* `extract-tags` - use a `tagExtractor` to extract information from the parsed tags.
+* `inline-tags` - Search the docs for inline tags that need to have content injected
+* `tagDefinitions` - provides a collection of tag definitions, and a map of the same, to be used by
+the `tagParser` and `tagExtractor`.
+* `tagExtractor` - provides a service to extract tags information and convert it to specific
+properties on the document, based on a set of tag-definitions.
+The `jsdoc` package contains definitions for a number of standard jsdoc tags including: `name`,
+`memberof`, `param`, `property`, `returns`, `module`, `description`, `usage`,
+`animations`, `constructor`, `class`, `classdesc`, `global`, `namespace`, `method`, `type` and
+`kind`.
+* `tagParser` - provides a service to parse the content of a document to get all the jsdoc style
+tags out.
 
-This package does not provide any templates.
+**This package does not provide any templates nor a `templateEngine` to render templates (use the
+`nunjucks` package to add this).**
 
 ### `ngdoc` Package
 
-There is one new document extractor in this package, `ngdoc`, which can pull a single document from
-an ngdoc content file.
+The `ngdoc` Package also loads up the `jsdoc` and `nunjucks` packages automatically.
 
-On top of the processors provided by the `jsdoc` package, this packages adds the following processors:
+This package contains the following file readers, in addition to those provided by the `jsdocs`
+package:
 
-* `filter-ngdocs` -
-For AngularJS we are only interested in documents that contain the @ngdoc tag.  This processor
-removes docs that do not contain this tag.
+* `ngdoc` - can pull a single document from an ngdoc content file.
 
-* `memberof` -
-All docs that have a `@memberof` tag are attached to their parent document and removed from the top
-level list of docs.
+On top of the processors provided by the `jsdoc` package, this packages adds the following processors:
 
-* `links` -
-Parse all `{@link ... }` inline tags in the docs and replace with real anchors.  This processor is
-able to compute URLs for code references.
-
-* `examples` -
-Parse the `<example>` tags from the content, generating new docs that will be converted to extra
-files that can be loaded by the application and used, for example, in live in-place demos of the
-examples and e2e testing.
-
 * `api-docs` -
@@ -64,2 +90,13 @@ This processor runs a bunch of computations that are specifically related to docs for API components.
 
+* `component-groups-generate` -
+
+* `compute-id` -
+
+* `filter-ngdocs` -
+For AngularJS we are only interested in documents that contain the @ngdoc tag.  This processor
+removes docs that do not contain this tag.
+
+* `partial-names` -
+
+
 This package also provides a set of templates for generating an HTML file for each document: api,
@@ -69,3 +106,14 @@ directive, error, filter function, input, module, object, overview, provider, service, type and a
 
+### `examples` Package
 
+This package is a mix in that provides additional processors for working with examples in the docs:
+
+* `examples-parse` -
+Parse the `<example>` tags from the content, generating new docs that will be converted to extra
+files that can be loaded by the application and used, for example, in live in-place demos of the
+examples and e2e testing.
+* `examples-generate` -
+
+
+
 ## HTML Rendering
@@ -72,0 +120,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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

204477

increased by2.49%

Number of package files

142

increased by0.71%

Lines of code

4425

increased by1.44%

Number of lines in readme file

148

increased by48%

Number of medium supply chain risk alerts

7

decreased by-12.5%

No dependency changes