dgeni-packages - npm Package Compare versions

Comparing version 0.11.0 to 0.11.1

CHANGELOG.md

 # Changelog
 
+## v0.11.1 7 November 2015
+
+* fix(jsdoc/inline-tags): don't conflate successive inline tags when matching Peter Bacon Darwin  67c2abf5
+* feat(jsdoc): add license tag  Peter Bacon Darwin  6f4bb5f7
+* feat(docs): improve templates and add npm script for generating docs  Peter Bacon Darwin  3c75243e
+* feat(dgeni): compute the full pipeline of processors for each package and add index page  Peter Bacon Darwin  c12cd9ec
+
+
 ## v0.11.0 31 October 2015
@@ -4,0 +12,0 @@

dgeni/index.js

@@ -18,2 +18,4 @@ var Package = require('dgeni').Package;
 .processor(require('./processors/wireUpServicesToPackages'))
+.processor(require('./processors/generateIndex'))
+.processor(require('./processors/computeProcessorPipeline'))
 
@@ -31,3 +33,3 @@ .config(function(parseTagsProcessor, getInjectables) {
   computeIdsProcessor.idTemplates.push({
-    docTypes: ['dgPackage'],
+    docTypes: ['dgPackage', 'indexPage'],
     idTemplate: '${name}',
@@ -44,3 +46,3 @@ getAliases: function(doc) { return [doc.id]; }
   // TODO: When using this package you will need to provide
-  // * path templates to the computePathsProcessor for dgPackage, dgProcessor and dgService
+  // * path templates to the computePathsProcessor for indexPage, dgPackage, dgProcessor and dgService
   // * rendered content templates to the templateFinder

docs/index.js

@@ -33,3 +33,3 @@ // Canonical path provides a consistent path (i.e. always forward slashes) across different OSes
   computePathsProcessor.pathTemplates.push({
-    docTypes: ['dgPackage'],
+    docTypes: ['dgPackage', 'indexPage'],
     pathTemplate: '${id}.md',
@@ -36,0 +36,0 @@ outputPathTemplate: '${path}'

docs/templates/dgPackage.template.md

@@ -1,7 +0,13 @@
-# {$ doc.name $} package
+{% include 'partials/header.template.md' %}
+## {$ doc.name $} package
 
 {$ doc.description $}
 
-## Dependencies
+### Dependencies
 
+{% if doc.dependencies.length %}
+This package depends upon:
+{% else %}
+This package has no dependencies.
+{% endif %}
 {% for dependency in doc.dependencies %}
@@ -11,7 +17,12 @@ * {@link {$ dependency.name $} }
 
+### Processors
 
-## Processors
-
+{% if doc.processors.length %}
+Processors that are defined in this package:
+{% else %}
+There are no processors defined in this package.
+{% endif %}
 {% for processor in doc.processors %}
-* {@link {$ processor.id $} }
+* **{@link {$ processor.id $} }**
+{$ processor.description $}
 {% endfor %}
@@ -21,4 +32,19 @@
 
+{% if doc.services.length %}
+Services that are defined in this package:
+{% else %}
+There are no services defined in this package.
+{% endif %}
 {% for service in doc.services %}
-* {@link {$ service.id $} }
+* **{@link {$ service.id $} }**
+{$ service.description $}
 {% endfor %}
+
+### Pipeline
+
+The full pipeline of processors for this package:
+
+{% for p in doc.pipeline %}
+* {% if p.$process %}**{% endif %}{@link {$ p.id $} {$ p.name $} }{% if p.$process %}**{% endif %}
+  ({@link {$ p.packageDoc.id $} {$ p.packageDoc.name $} }){% endfor %}
+

docs/templates/dgProcessor.template.md

@@ -1,3 +0,4 @@
-# {$ doc.name $} processor {% if not doc.$process %}*(pseudo)*{% endif %}
-## from {@link {$ doc.packageDoc.id $} } package
+{% include 'partials/header.template.md' %}
+## {$ doc.name $} processor {% if not doc.$process %}*(pseudo)*{% endif %}
+**from {@link {$ doc.packageDoc.id $} } package**
 
@@ -4,0 +5,0 @@ {$ doc.description $}

docs/templates/dgService.template.md

@@ -1,5 +0,6 @@
-# {$ doc.name $} service
-## from {@link {$ doc.packageDoc.id $} } package
+{% include 'partials/header.template.md' %}
+## {$ doc.name $} service
+**from {@link {$ doc.packageDoc.id $} } package**
 
 {$ doc.description $}
 

jsdoc/processors/inline-tags.js

 var _ = require('lodash');
-var INLINE_TAG = /(\{@[^\s]+[^\}]*\})/;
-                        //  11111111   22222222
+var INLINE_TAG = /(\{@[^\s\}]+[^\}]*\})/;
+                        //  11111111     22222222
 var INLINE_TAG_DETAIL = /\{@([^\s]+)\s*([^\}]*)\}/;
@@ -112,29 +112,133 @@ var StringMap = require('stringmap');
         }
-        // if ( doc.renderedContent ) {
 
-        //   // Replace any inline tags found in the rendered content
-        //   doc.renderedContent = doc.renderedContent.replace(INLINE_TAG, function(match, tagName, tagDescription) {
+      });
+    }
+  };
+};
 
-        //     var definition = definitionMap.get(tagName);
-        //     if ( definition ) {
+function getMap(objects) {
+  var map = new StringMap();
+  _.forEach(objects, function(object) {
+    map.set(object.name, object);
+    if ( object.aliases ) {
+      _.forEach(object.aliases, function(alias) {
+        map.set(alias, object);
+      });
+    }
+  });
+  return map;
+}
 
-        //       try {
+var _ = require('lodash');
+var INLINE_TAG = /(\{@[^\s\}]+[^\}]*\})/;
+                        //  11111111     22222222
+var INLINE_TAG_DETAIL = /\{@([^\s]+)\s*([^\}]*)\}/;
+var StringMap = require('stringmap');
 
-        //         // It is easier to trim the description here than to fiddle around with the INLINE_TAG regex
-        //         tagDescription = tagDescription && tagDescription.trim();
+/**
+ * @dgProcessor inlineTagProcessor
+ * @description
+ * Search the docs for inline tags that need to have content injected.
+ *
+ * Inline tags are defined by a collection of inline tag definitions.  Each definition is an injectable function,
+ * which should create an object containing, as minimum, a `name` property and a `handler` method, but also,
+ * optionally, `description` and `aliases` properties.
+ *
+ * * The `name` should be the canonical tag name that should be handled.
+ * * The `aliases` should be an array of additional tag names that should be handled.
+ * * The `handler` should be a method of the form: `function(doc, tagName, tagDescription, docs) { ... }`
+ * The
+ * For example:
+ *
+ * ```
+ * function(partialNames) {
+ *   return {
+ *     name: 'link',
+ *     handler: function(doc, tagName, tagDescription, docs) { ... }},
+ *     description: 'Handle inline link tags',
+ *     aliases: ['codeLink']
+ *   };
+ * }
+ * ```
+ */
+module.exports = function inlineTagProcessor(log, createDocMessage) {
+  return {
+    inlineTagDefinitions: [],
+    $runAfter: ['docs-rendered'],
+    $runBefore: ['writing-files'],
+    $process: function(docs) {
 
-        //         // Call the handler with the parameters that its factory would not have been able to get from the injector
-        //         return definition.handler(doc, tagName, tagDescription, docs);
+      var definitions = this.inlineTagDefinitions;
+      var definitionMap = getMap(definitions);
 
-        //       } catch(e) {
-        //         throw new Error(createDocMessage('There was a problem running the @' + tagName + ' inline tag handler for ' + match, doc, e));
-        //       }
+      // Walk the docs and parse the inline-tags
+      _.forEach(docs, function(doc) {
 
-        //     } else {
-        //       log.warn(createDocMessage('No handler provided for inline tag "' + match + '"', doc));
-        //       return match;
-        //     }
+        if ( doc.renderedContent ) {
+          // This is a stack of start-end tag instances
+          // as a new start-end tag is found it is unshifted onto the front of this array
+          // Each item looks like: { definition: tagDef, value: { tag: '...', content: '...' } }
+          var pendingTags = [];
 
-        //   });
-        // }
+          // The resulting array from the split is alternating plain content and inline tags
+          var parts = doc.renderedContent.split(INLINE_TAG);
+
+          doc.renderedContent = parts.reduce(function(renderedContent, nextPart) {
+
+            var match = INLINE_TAG_DETAIL.exec(nextPart);
+
+            if (match) {
+
+              // We have a new tag
+              var tagName = match[1];
+              var tagDescription = match[2] && match[2].trim();
+              if (pendingTags.length > 0 && tagName === pendingTags[0].definition.end) {
+
+                // We have found a matching end tag. Remove it from the stack and run its handler
+                var pendingTag = pendingTags.shift();
+                var startTag = pendingTag.definition;
+
+                nextPart = startTag.handler(doc, startTag.name, pendingTag.value, docs);
+
+              } else {
+
+                // We have a new tag. Look it up in the definitions
+                var definition = definitionMap.get(tagName);
+
+                if (!definition) {
+
+                  // There is no matching tag definition
+                  log.warn(createDocMessage('No handler provided for inline tag "' + match[0] + '"', doc));
+                  nextPart = match[0];
+
+                } else if(definition.end) {
+
+                  // We have a new start-end tag. Unshift it onto the pendingTags stack
+                  pendingTags.unshift({
+                    definition: definition,
+                    value: {
+                      tag: tagDescription,
+                      content: ''
+                    }
+                  });
+
+                  nextPart = '';
+
+                } else {
+
+                  // We have a new normal tag. Run its handler
+                  nextPart = definition.handler(doc, definition.name, tagDescription, docs);
+                }
+              }
+            } else if (pendingTags.length) {
+              // We have some plain content but we are inside a start-end tag
+              // Add this content to the current start-end tag
+              pendingTags[0].value.content += nextPart;
+              nextPart = '';
+            }
+
+            return renderedContent + nextPart;
+          });
+        }
+
       });
@@ -141,0 +245,0 @@ }

jsdoc/processors/inline-tags.spec.js

@@ -123,2 +123,57 @@ var mockPackage = require('../mocks/mockPackage');
     });
+
+    it("should not get confused by successive inline tags", function() {
+      var doc = {
+        file: 'a/b/c.js',
+        startingLine: 123,
+        renderedContent:
+          '{@block param1 param2}' +
+          'content within the inline tag' +
+          '{@endblock} ' +
+          '{@block param3 param4}' +
+          'more content within another inline tag' +
+          '{@endblock}'
+      };
+      var docs = [doc];
+
+      // Provide a mock tag handler to track what tags have been handled
+      var tagsFound = [];
+      var mockInlineTagDefinition = {
+        name: 'block',
+        end: 'endblock',
+        handler: function(doc, tagName, tagDescription, docs) {
+          tagsFound.push({ name: tagName, description: tagDescription });
+          return '<Tag Handled>';
+        }
+      };
+
+      processor.inlineTagDefinitions = [mockInlineTagDefinition];
+
+      // Run the processor
+      var results = processor.$process(docs);
+
+      // This processor should not return anything.  All its work is done on the docs, in place
+      expect(results).toBeUndefined();
+
+
+      // We expect the handler to have been invoked for the block tag
+      expect(tagsFound).toEqual([
+        {
+          name: 'block',
+          description: {
+            tag: 'param1 param2',
+            content: 'content within the inline tag'
+          }
+        },
+        {
+          name: 'block',
+          description: {
+            tag: 'param3 param4',
+            content: 'more content within another inline tag'
+          }
+        }
+      ]);
+
+      expect(doc.renderedContent).toEqual('<Tag Handled> <Tag Handled>');
+    });
   });
@@ -125,0 +180,0 @@

jsdoc/tag-defs/index.js

@@ -24,3 +24,4 @@
   require('./function'),
-  require('./method')
+  require('./method'),
+  require('./license')
 ];

jsdoc/tag-defs/index.spec.js

@@ -6,3 +6,3 @@ var tagDefFactories = require('./');
     expect(tagDefFactories).toEqual(jasmine.any(Array));
-    expect(tagDefFactories.length).toEqual(22);
+    expect(tagDefFactories.length).toEqual(23);
     tagDefFactories.forEach(function(factory) {
@@ -9,0 +9,0 @@ expect(factory).toEqual(jasmine.any(Function));

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "A collection of dgeni packages for generating documentation from source code",
   "scripts": {
     "test": "jasmine-node .",
-    "cover": "istanbul cover jasmine-node -- ."
+    "cover": "istanbul cover jasmine-node -- .",
+    "docs": "dgeni ./docs"
   },
@@ -53,2 +54,3 @@ "repository": {
     "shelljs": "^0.5.0",
+    "spdx-license-list": "^2.1.0",
     "stringmap": "^0.2.2",
@@ -55,0 +57,0 @@ "winston": "~0.7.2"

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

394168

increased by2.31%

Number of package files

275

increased by2.23%

Lines of code

7763

increased by2.7%

Worsened metrics

Dependency count

21

increased by5%

Dependency changes

• + Addedspdx-license-list@^2.1.0

• + Addedspdx-license-list@2.1.0(transitive)