dgeni-packages - npm Package Compare versions

Comparing version 0.10.0 to 0.10.1

base/index.js

@@ -31,4 +31,7 @@ var Package = require('dgeni').Package;
 .processor(require('./processors/computePaths'))
+.processor(require('./processors/checkAnchorLinks'))
 
 // Helper services
+.factory(require('./services/resolveUrl'))
+.factory(require('./services/extractLinks'))
 .factory(require('./services/templateFinder'))
@@ -39,2 +42,2 @@ .factory(require('./services/encodeCodeBlock'))
 .factory(require('./services/createDocMessage'))
-.factory(require('./services/writeFile'));
+.factory(require('./services/writeFile'));

base/processors/computePaths.js

@@ -54,3 +54,3 @@ var _ = require('lodash');
             if ( !getPath ) {
-              log.debug(createDocMessage('No path template provided', doc));
+              log.warn(createDocMessage('No path template provided', doc));
             } else {
@@ -64,3 +64,3 @@ doc.path = getPath(doc);
             if ( !getOutputPath ) {
-              log.debug(createDocMessage('No output path template provided', doc));
+              log.warn(createDocMessage('No output path template provided', doc));
             } else {
@@ -75,3 +75,3 @@ doc.outputPath = getOutputPath(doc);
 
-        log.debug('computed path for:', '"' + doc.id + '" (' + doc.docType + ') - "' + doc.path + '"', 'and outputPath:', '"' + doc.outputPath + '"');
+        log.debug(createDocMessage('path: ' + doc.path + '; outputPath: ' + doc.outputPath, doc));
       });
@@ -78,0 +78,0 @@ }

CHANGELOG.md

 # Changelog
 
+## v0.10.1 6th October
+
+Mostly minor refactoring and the new `checkAnchorLinksProcessor`
+
+Thanks to Lucas, Thor and Stéphane.
+
+* refact(base/checkAnchorLinksProcessor): cleaned up the processor     537f6228
+* refact(base/extractLinks): rename and also extract id attributes     3ef7b3af
+* refact(base/resolveUrl): simplify the code       f393d4ac
+* feat(anchors): detect dangling anchors     b9b3ef8c
+* refact(base/computePathsProcessor): warn if no path or outputPath template/getter is found       a5b9f536
+* refact(jsdoc/jsdocfileReader): move processing into extractJSDocCommentsProcessor     cbcbac23
+* feat(jsdoc/extractJSDocComments): add new processor      b1362834
+* fix(jsdoc/parseTagsProcessor): don't error if doc has no content      b3da03c3
+* feat(ngdoc/templates/base.template): make 'Improve this Doc' lead to appropriate line      55f5f002
+
+
 ## v0.10.0 29th September 2014
@@ -4,0 +21,0 @@

examples/index.js

@@ -31,2 +31,3 @@ var path = require('canonical-path');
     docTypes: ['example-file'],
+    getPath: function() {},
     outputPathTemplate: 'examples/${id}'
@@ -36,3 +37,4 @@ });
     docTypes: ['runnableExample' ],
-    pathTemplate: 'examples/${example.id}'
+    pathTemplate: 'examples/${example.id}',
+    getOutputPath: function() {},
   });
@@ -39,0 +41,0 @@

jsdoc/file-readers/jsdoc.js

 var _ = require('lodash');
-var jsParser = require('esprima');
-var traverse = require('estraverse').traverse;
-var LEADING_STAR = /^[^\S\r\n]*\*[^\S\n\r]?/gm;
+var esprima = require('esprima');
 
@@ -9,15 +7,4 @@ /**
  * @description
- * This file reader will pull a doc for each jsdoc style comment in the source file
- * (by default .js)
- *
- * The doc will initially have the form:
- * ```
- * {
- *   content: 'the content of the comment',
- *   startingLine: xxx,
- *   endingLine: xxx,
- *   codeNode: someASTNode
- *   codeAncestors: arrayOfASTNodes
- * }
- * ```
+ * This file reader will create a simple doc for each js
+ * file including a code AST of the JavaScript in the file.
  */
@@ -30,58 +17,12 @@ module.exports = function jsdocFileReader() {
 
-      fileInfo.ast = jsParser.parse(fileInfo.content, {
+      fileInfo.ast = esprima.parse(fileInfo.content, {
         loc: true,
-        range: true,
-        comment: true
+        attachComment: true
       });
 
-      return _(fileInfo.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
-          text = comment.value.replace(LEADING_STAR, '');
-
-          // Trim off leading and trailing whitespace
-          text = text.trim();
-
-          // Extract the information about the code directly after this comment
-          var codeNode = findNodeAfter(fileInfo.ast, comment.range[1]);
-
-          // Create a doc from this comment
-          return {
-            startingLine: comment.loc.start.line,
-            endingLine: comment.loc.end.line,
-            content: text,
-            codeNode: codeNode.node,
-            codeAncestors: codeNode.path,
-            docType: 'js'
-          };
-
-        })
-
-        .value();
+      return [{
+        docType: 'jsFile'
+      }];
     }
   };
-};
-
-function findNodeAfter(ast, pos) {
-  var found, path;
-  traverse(ast, {
-    enter: function(node) {
-      if ( node.range[1] > pos && node.range[0] >= pos ) {
-        if ( !found || found.range[0] >= node.range[0] ) {
-          found = node;
-          path = this.parents();
-          this.skip();
-        }
-      }
-    }
-  });
-  return { node: found, path: path };
-}
+};

jsdoc/file-readers/jsdoc.spec.js

 var path = require('canonical-path');
 var fileReaderFactory = require('./jsdoc');
 
-var srcJsContent = require('./_test-data/srcJsFile.js');
-var docsFromJsContent = require('./_test-data/docsFromJsFile');
+var srcJsContent = require('../mocks/_test-data/srcJsFile.js');
+var docsFromJsContent = require('../mocks/_test-data/docsFromJsFile');
 
@@ -38,43 +38,12 @@
 
-  describe("process", function() {
+  describe("getDocs", function() {
 
-    it('should return a collection of documents extracted from the file', function() {
+    it('should return a single doc representing the file', function() {
       var fileInfo = createFileInfo('some/file.js', srcJsContent, '.');
       var docs = fileReader.getDocs(fileInfo);
-      expect(docs.length).toEqual(3);
-      expect(docs[0]).toEqual(jasmine.objectContaining(docsFromJsContent[0]));
-      expect(docs[1]).toEqual(jasmine.objectContaining(docsFromJsContent[1]));
-      expect(docs[2]).toEqual(jasmine.objectContaining(docsFromJsContent[2]));
-    });
-
-    it("should set the docType to js", function() {
-      var fileInfo = createFileInfo('some/file.js', '/** @some jsdoc comment */', '.');
-      var docs = fileReader.getDocs(fileInfo);
-      expect(docs[0].docType).toEqual('js');
-    });
-
-
-    it("should strip off the leading whitespace/stars from each line of the comments", function() {
-      var fileInfo = createFileInfo('some/file.js', '/** abc  \n  * other stuff  \n\t\t*last line.\n*/\n', '.');
-      var docs = fileReader.getDocs(fileInfo);
-      expect(docs[0].content).toEqual('abc  \nother stuff  \nlast line.');
-    });
-
-
-    it("should ignore non-jsdoc comments", function() {
-      var fileInfo = createFileInfo('some/file.js', '/** Some jsdoc comment */\n// A line comment\n\/* A non-jsdoc block comment*/', '.');
-      var docs = fileReader.getDocs(fileInfo);
       expect(docs.length).toEqual(1);
+      expect(docs[0]).toEqual(jasmine.objectContaining({ docType: 'jsFile' }));
     });
 
 
-    it("should find the next code item following the comment and attach it to the doc", function() {
-      var fileInfo = createFileInfo('some/file.js', srcJsContent, '.');
-      var docs = fileReader.getDocs(fileInfo);
-      expect(docs.length).toEqual(3);
-      expect(docs[0].codeNode.type).toEqual('FunctionDeclaration');
-      expect(docs[1].codeNode.type).toEqual('ExpressionStatement');
-      expect(docs[2].codeNode.type).toEqual('ReturnStatement');
-    });
-
     it("should attach the AST to the fileInfo", function() {
@@ -89,17 +58,3 @@ var fileInfo = createFileInfo('some/file.js', srcJsContent, '.');
 
-    it("should not break if the comment has no code", function() {
-      var fileInfo = createFileInfo('some/file.js', 'function main() { } /** @some jsdoc comment */', '.');
-      expect(function() {
-        var docs = fileReader.getDocs(fileInfo);
-        expect(docs.length).toEqual(1);
-      }).not.toThrow();
-    });
-
-
-    it("should not remove windows new line characters when stripping stars from comments", function() {
-      var fileInfo = createFileInfo('some/file.js', '/** Some jsdoc comment\r\n* over multiple\r\n* lines\r\n**/', '.');
-      var docs = fileReader.getDocs(fileInfo);
-      expect(docs[0].content).toEqual('Some jsdoc comment\r\nover multiple\r\nlines');
-    });
   });
 });

jsdoc/index.js

@@ -13,2 +13,3 @@ var path = require('canonical-path');
 // Add in the real processors for this package
+.processor(require('./processors/extractJSDocComments'))
 .processor(require('./processors/code-name'))
@@ -15,0 +16,0 @@ .processor(require('./processors/parse-tags'))

jsdoc/processors/parse-tags.js

@@ -24,3 +24,3 @@ var _ = require('lodash');
         try {
-          doc.tags = tagParser(doc.content, doc.startingLine);
+          doc.tags = tagParser(doc.content || '', doc.startingLine);
         } catch(e) {
@@ -27,0 +27,0 @@ var message = createDocMessage('Error parsing tags', doc, e);

jsdoc/processors/parse-tags.spec.js

@@ -92,2 +92,9 @@ var mockPackage = require('../mocks/mockPackage');
     });
+
+
+    it("should ignore doc if it has no content", function() {
+      expect(function() {
+        processor.$process([{}]);
+      }).not.toThrow();
+    });
 });

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "A collection of dgeni packages for generating documentation from source code",
@@ -43,2 +43,3 @@ "scripts": {
     "glob": "~3.2.8",
+    "htmlparser2": "^3.7.3",
     "lodash": "~2.4.1",
@@ -74,4 +75,5 @@ "marked": "^0.3.2",
     "Thor Jacobsen <[e-mail]>",
-    "<[e-mail]>"
+    "<[e-mail]>",
+    "Lucas Galfaso <[e-mail]>"
   ]
 }

README_fr_FR.md

@@ -229,7 +229,52 @@ # Dgeni Packages
 comme des fichiers qui peuvent être exécutés dans le navigateur, par exemple des démos en direct ou pour
-des tests de e2e.
+des tests de e2e. Ce processeur doit être configuré avec une collection des différents déploiements qui lui indiquera
+la version à générer pour chaque exemple . Voir la section de **Configuration de déploiement** ci-dessous.
 * `parseExamplesProcessor` - Analyse les balises `<example>` depuis le contenu et les ajoute au service `examples`
-* `generateProtractorTests` - Génère les fichiers de test de protractor depuis les tests e2e dans les exemples
+* `generateProtractorTestsProcessor` - Génère les fichiers de test de protractor depuis les tests e2e dans les exemples. Ce processeur
+doit être configuré avec une collection des différents déploiements qui lui indiquera la version des tests de protaractor à générer. Voir la
+section de **Configuration de déploiement** ci-dessous.
 
+#### Configuration de déploiement
 
+Les processeurs `generateExamplesProcessor` et `generateProtractorTestsProcessor` ont une propriété *obligatoire* appelée `deployments`.
+Cette propriété doit être un tableau d'objets d'information de déploiement indiquant au processeur quels sont les fichiers à générer.
+
+Par exemple, vous pourriez avoir un déploiement "debug" qui charge angular.js dans l'exemple et un déploiement "default" qui
+charge angular.min.js dans l'exemple. De même, vous pourriez avoir des déploiements qui utilisent JQuery et certains qui utilisent
+uniquement jqLite de Angular.
+
+Vous pouvez configurer cela dans votre package comme ceci :
+
+```js
+.config(function(generateExamplesProcessor, generateProtractorTestsProcessor) {
+  var deployments = [
+    { name: 'debug', ... },
+    { name: 'default', ... }
+  ];
+
+  generateExamplesProcessor.deployments = deployments;
+  generateProtractorTestsProcessor.deployments = deployments;
+});
+```
+
+Un déploiement doit avoir une propriété `name` et peut également inclure une propriété `examples` qui contient
+des informations à propos du chemin et des fichiers supplémentaires à injecter dans des exemples.
+De plus, un test de protractor est généré pour chaque déploiement et il utilise le nom du déploiement pour trouver le
+chemin de l'exemple associé à ce déploiement.
+
+```js
+{
+  name: 'default',
+  examples: {
+    commonFiles: {
+      scripts: [ '../../../angular.js' ]
+    },
+    dependencyPath: '../../../'
+  }
+}
+```
+
+Ici nous avons un déploiement `default` qui injecte le fichier `angular.js` dans tous les exemples,
+ainsi que les dépendances référencées dans l'exemple qui sont placées par rapport à la donnée `dependencyPath`.
+
 ### Définitions des balises Inline
@@ -236,0 +281,0 @@

README.md

@@ -229,7 +229,52 @@ # Dgeni Packages
 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.
+examples or for e2e testing. This processor must be configured with a collection of deployments that tell it
+what versions of each example to generate. See the section of **Deployment Configuration** below.
 * `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
+* `generateProtractorTestsProcessor` - Generate a protractor test files from the e2e tests in the examples. This processor
+must be configured with a collection of deployments that tell versions of the protractor tests to generate. See the
+section of **Deployment Configuration** below.
 
+#### Deployment Configuration
 
+The `generateExamplesProcessor` and `generateProtractorTestsProcessor` processors have a *required* property called `deployments`.
+This property should be an array of deployment information objects telling the processor what files to generate.
+
+For instance you might have a "debug" deployment that loads angular.js into the example, and also a "default" deployment that
+loads angular.min.js into the example. Equally you might have deployments that use JQuery and some that only use Angular's
+jqLite.
+
+You can configure this in your package like so:
+
+```js
+.config(function(generateExamplesProcessor, generateProtractorTestsProcessor) {
+  var deployments = [
+    { name: 'debug', ... },
+    { name: 'default', ... }
+  ];
+
+  generateExamplesProcessor.deployments = deployments;
+  generateProtractorTestsProcessor.deployments = deployments;
+});
+```
+
+A deployment can must have a `name` property and can also include an `examples` property that contains
+information about paths and extra files to inject into runtime examples.
+Further a protractor test is generated for each deployment and it uses the deployment name to find the
+path to the associated example for that deployment.
+
+```js
+{
+  name: 'default',
+  examples: {
+    commonFiles: {
+      scripts: [ '../../../angular.js' ]
+    },
+    dependencyPath: '../../../'
+  }
+}
+```
+
+Here you can see we have a `default` deployment that injects the `angular.js` file into all examples,
+plus any dependencies referenced in the example itself are made relative to the given `dependencyPath`.
+
 ### Inline Tag Definitions
@@ -236,0 +281,0 @@

No alert changes

Improved metrics

Total package byte prevSize

317928

increased by7.75%

Number of package files

230

increased by3.6%

Lines of code

6031

increased by7.33%

Number of lines in readme file

289

increased by18.44%

Worsened metrics

Dependency count

18

increased by5.88%

Dependency changes

• + Addedhtmlparser2@^3.7.3

• + Addeddom-serializer@0.2.2(transitive)

• + Addeddomelementtype@1.3.12.3.0(transitive)

• + Addeddomhandler@2.4.2(transitive)

• + Addeddomutils@1.7.0(transitive)

• + Addedentities@1.1.22.2.0(transitive)

• + Addedhtmlparser2@3.10.1(transitive)

• + Addedreadable-stream@3.6.2(transitive)

• + Addedsafe-buffer@5.2.1(transitive)

• + Addedstring_decoder@1.3.0(transitive)

• + Addedutil-deprecate@1.0.2(transitive)