ndoc - npm Package Compare versions

Comparing version 2.0.1 to 2.0.2

bin/ndoc.js

@@ -76,2 +76,10 @@ #!/usr/bin/env node
 //
+// Process aliases
+//
+
+options.aliases.forEach(function (pair) {
+  NDoc.extensionAlias.apply(null, pair.split(':'));
+});
+
+//
 // Post-process some of the options
@@ -78,0 +86,0 @@ //

HISTORY.md

@@ -1,4 +0,11 @@
-2.0.1 / In development
-----------------------
+2.0.2 / 2012-07-19
+------------------
 
+* Add `--alias <from>:<to>` option. Closes #58.
+* [API] cli.findFiles now support functions.
+
+
+2.0.1 / 2012-07-08
+------------------
+
 * Enhance `.ndocrc` reader to support comments.
@@ -5,0 +12,0 @@

lib/ndoc.js

@@ -65,3 +65,2 @@ /**
     if (!fn) {
-      console.warn('No parser found for file: ' + file);
       next_file();
@@ -380,3 +379,3 @@ return;
  *  NDoc.registerParser(extension, func) -> Void
- *  - extension (String): Extension suitable for the parser, e.g. `'.js'`
+ *  - extension (String): Extension suitable for the parser, e.g. `'js'`
  *  - func (Function): Parser function `func(source, options, callback)`
@@ -387,6 +386,43 @@ *
 NDoc.registerParser = function (extension, func) {
-  parsers[path.extname('name.' + extension)] = func;
+  extension = path.extname('name.' + extension);
+
+  Object.defineProperty(parsers, extension, {
+    get: function () { return func; },
+    configurable: true
+  });
 };
 
 
+/**
+ *  NDoc.extensionAlias(alias, extension) -> Void
+ *  - alias (String): Extension as for the parser, e.g. `'cc'`
+ *  - extension (String): Extension as for the parser, e.g. `'js'`
+ *
+ *  Registers `alias` of the `extension` parser.
+ *
+ *
+ *  ##### Example
+ *
+ *  Parse all `*.cc` files with parser registered for `*.js`
+ *
+ *  ``` javascript
+ *  ndoc.extensionAlias('cc', 'js');
+ *  ```
+ *
+ *
+ *  ##### See Also
+ *
+ *  - [[NDoc.registerParser]]
+ **/
+NDoc.extensionAlias = function (alias, extension) {
+  alias     = path.extname('name.' + alias);
+  extension = path.extname('name.' + extension);
+
+  Object.defineProperty(parsers, alias, {
+    get: function () { return parsers[extension]; },
+    configurable: true
+  });
+};
+
+
 //
@@ -393,0 +429,0 @@ // require base plugins

lib/ndoc/cli.js

@@ -115,2 +115,12 @@ /**
 
+cli.addArgument(['--alias'], {
+  dest:         'aliases',
+  help:         'Registers extensions alias. For example `cc:js` will ' +
+                'register `cc` extension as an alias of `js`',
+  metavar:      'MAPPING',
+  action:       'append',
+  defaultValue: []
+});
+
+
 cli.addArgument(['-r', '--render'], {
@@ -179,5 +189,5 @@ dest:         'renderer',
 /**
- *  cli.findFiles(paths, excludes, callback(err, files)) -> Void
+ *  cli.findFiles(paths[, excludes], callback(err, files)) -> Void
  *  - paths (Array): List of directories/files
- *  - excludes (Array): List of glob patterns. See minimatch for pattern syntax.
+ *  - excludes (Array): List of glob patterns.
  *  - callback (Function)
@@ -189,2 +199,19 @@ *
  *
+ *  ##### Excluding paths
+ *
+ *  Each element of `excludes` list might be either a `String` pattern with
+ *  wildcards (`*`, `**`, `?`, etc., see minimatch module for pattern syntax) or
+ *  a `Function` that returns boolean (whenever excude or not) and executed with
+ *  `(filename, lstats)`.
+ *
+ *
+ *      var excludes = [
+ *        'lib/parser-*.js',
+ *        function (filename, lstats) {
+ *          // skip any symlink
+ *          return lstats.isSymbolicLink());
+ *        }
+ *      ];
+ *
+ *
  *  ##### See Also
@@ -197,10 +224,12 @@ *
 
+  // SCENARIO: findFiles(['lib'], callback);
   if (_.isFunction(excludes)) {
     callback = excludes;
-    excludes = [];
+    // set default value later
+    excludes = null;
   }
 
-  // prepare glob matchers
+  // prepare matchers matchers
   excludes = _.map(excludes || [], function (p) {
-    return minimatch.makeRe(p);
+    return _.isFunction(p) ? {test: p} : minimatch.makeRe(p);
   });
@@ -211,22 +240,18 @@
 
-  function done(err) {
-    if (err) {
-      callback(err);
-      return;
-    }
+  function process(filename, lstats) {
+    var include = true;
 
-    if (excludes.length) {
-      entries = _.filter(entries, function (filename) {
-        var js = '.js' === path.extname(filename),
-            ok = !_.any(excludes, function (re) { return re.test(filename); });
-
-        return js && ok;
+    if (0 < excludes.length) {
+      include = !_.any(excludes, function (filter) {
+        return filter.test(filename, lstats);
       });
     }
 
-    callback(null, entries.sort());
+    if (include) {
+      entries.push(filename);
+    }
   }
 
   function walk(err) {
-    var pathname;
+    var pathname, lstats;
 
@@ -238,9 +263,12 @@ // get next path
     if (err || !pathname) {
-      done(err);
+      callback(err, entries.sort());
       return;
     }
 
-    if (!fs.statSync(pathname).isDirectory()) {
-      // add non-directories directly
-      entries.push(pathname);
+    // get lstats of the pathname
+    lstats = fs.lstatSync(pathname);
+
+    if (!lstats.isDirectory()) {
+      // process non-directories directly
+      process(pathname, lstats);
       walk();
@@ -250,4 +278,4 @@ return;
 
-    FsTools.walk(pathname, function (filename, stats, next) {
-      entries.push(filename);
+    FsTools.walk(pathname, function (filename, lstats, next) {
+      process(filename, lstats);
       next();
@@ -254,0 +282,0 @@ }, walk);

package.json

 {
   "name"            : "ndoc",
-  "version"         : "2.0.1",
+  "version"         : "2.0.2",
   "description"     : "JavaScript API documentor with simple syntax.",
@@ -5,0 +5,0 @@ "keywords"        : [

README.md

@@ -28,42 +28,47 @@ # NDoc - JavaScript documentation generator
 
-    usage: ndoc [-h] [-v] [--exclude PATTERN] [-o PATH] [--use PLUGIN]
-                [-r RENDERER] [--link-format FORMAT] [-t TEMPLATE] [--show-all]
-                [--package PACKAGE] [--index FILE] [--gh-ribbon URL]
-                [--broken-links ACTION] [--noenv]
-                PATH[PATH ...]
+```
+usage: ndoc [-h] [-v] [--exclude PATTERN] [-o PATH] [--use PLUGIN]
+            [--alias MAPPING] [-r RENDERER] [--link-format FORMAT]
+            [-t TEMPLATE] [--show-all] [--package PACKAGE] [--index FILE]
+            [--gh-ribbon URL] [--broken-links ACTION] [--noenv]
+            PATH[PATH ...]
 
-    Positional arguments:
-      PATH                            Source files location
+Positional arguments:
+  PATH                            Source files location
 
-    Optional arguments:
-      -h, --help                      Show this help message and exit.
-      -v, --version                   Show program's version number and exit.
-      --exclude PATTERN               Glob patterns of filenames to exclude (you 
-                                      can use wildcards: ?, *, **).
-      -o PATH, --output PATH          Resulting file(s) location.
-      --use PLUGIN                    Load custom plugin.
-      -r RENDERER, --render RENDERER  Documentation renderer (html, json). More 
-                                      can be added by custom plugins.
-      --link-format FORMAT            View sources link (no links by default) 
-                                      format. You can use `{file}` and `{line}` 
-                                      and any of `{package.*}` variables for 
-                                      interpolation.
-      -t TEMPLATE, --title TEMPLATE   Documentation title template. You can use 
-                                      any of `{package.*}` variables for 
-                                      interpolation. DEFAULT: `{package.name} 
-                                      {package.version} API documentation`
-      --show-all                      By default `internal` methods/properties 
-                                      are not shown. This trigger makes ndoc show 
-                                      all methods/properties
-      --package PACKAGE               Read specified package.json FILE. When not 
-                                      specified, read ./package.json if such file 
-                                      exists.
-      --index FILE                    Index file (with introduction text), e.g. 
-                                      README.md file.
-      --gh-ribbon URL                 Add "Fork me on GitHub" ribbon with given 
-                                      URL. You can use any of `{package.*}` 
-                                      variables for interpolation.
-      --broken-links ACTION           What to do if broken link occurred (show, 
-                                      hide, throw). DEFAULT: `show`.
-      --noenv                         Ignore .ndocrc
+Optional arguments:
+  -h, --help                      Show this help message and exit.
+  -v, --version                   Show program's version number and exit.
+  --exclude PATTERN               Glob patterns of filenames to exclude (you 
+                                  can use wildcards: ?, *, **).
+  -o PATH, --output PATH          Resulting file(s) location.
+  --use PLUGIN                    Load custom plugin.
+  --alias MAPPING                 Registers extensions alias. For example 
+                                  `cc:js` will register `cc` extension as an 
+                                  alias of `js`
+  -r RENDERER, --render RENDERER  Documentation renderer (html, json). More 
+                                  can be added by custom plugins.
+  --link-format FORMAT            View sources link (no links by default) 
+                                  format. You can use `{file}` and `{line}` 
+                                  and any of `{package.*}` variables for 
+                                  interpolation.
+  -t TEMPLATE, --title TEMPLATE   Documentation title template. You can use 
+                                  any of `{package.*}` variables for 
+                                  interpolation. DEFAULT: `{package.name} 
+                                  {package.version} API documentation`
+  --show-all                      By default `internal` methods/properties 
+                                  are not shown. This trigger makes ndoc show 
+                                  all methods/properties
+  --package PACKAGE               Read specified package.json FILE. When not 
+                                  specified, read ./package.json if such file 
+                                  exists.
+  --index FILE                    Index file (with introduction text), e.g. 
+                                  README.md file.
+  --gh-ribbon URL                 Add "Fork me on GitHub" ribbon with given 
+                                  URL. You can use any of `{package.*}` 
+                                  variables for interpolation.
+  --broken-links ACTION           What to do if broken link occurred (show, 
+                                  hide, throw). DEFAULT: `show`.
+  --noenv                         Ignore .ndocrc
+```
 
@@ -70,0 +75,0 @@

No alert changes

Improved metrics

Total package byte prevSize

429193

increased by0.46%

Lines of code

10092

increased by0.64%

Number of lines in readme file

136

increased by3.82%

No dependency changes