sassdoc - npm Package Compare versions

Comparing version 0.3.4 to 0.3.5

package.json

@@ -5,3 +5,3 @@ {
   "author": "Hugo Giraudel",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "license": "MIT",
@@ -28,3 +28,4 @@ "repository": {
     "docopt": "^0.4.0",
-    "swig-extras": "0.0.1"
+    "swig-extras": "0.0.1",
+    "ncp": "^0.5.1"
   },
@@ -31,0 +32,0 @@ "bin": {

README.md

@@ -82,2 +82,12 @@ # SassDoc
 ```js
+{
+  'functions': [],
+  'mixins': [],
+  'variables': []
+}
+```
+
+Where a function/mixin is like this:
+
+```js
 [
@@ -113,2 +123,15 @@ {
 
+And a variable like this:
+
+```js
+{ 
+  type: 'variable',
+  datatype: ['Bool'],
+  description: 'Defines whether the lib should support legacy browsers (e.g. `IE 8`).',
+  name: 'support-legacy',
+  value: 'true',
+  access: 'global' 
+}
+```
+
 ## API Documentation
@@ -150,2 +173,4 @@
 
+The other function will automatically have a key named `aliased` containing the name of aliases.
+
 ### @author
@@ -205,2 +230,4 @@
 
+The other function will automatically have a key named `usedBy` containing the name of function requiring it.
+
 ### @returns (synonym: @return)
@@ -254,2 +281,3 @@
 
-Huge thanks to [Valérian Galliat](https://twitter.com/valeriangalliat) for the help.
+* [Valérian Galliat](https://twitter.com/valeriangalliat)
+* [Hugo Giraudel](http://twitter.com/HugoGiraudel)

src/file.js

 'use strict';
 
-var fs     = require('fs');
-var rimraf = require('rimraf');
-var swig   = require('swig');
-var extras = require('swig-extras');
-var Q      = require('q');
+var fs     = require('fs');          // File system
+var rimraf = require('rimraf');      // rm -rf
+var ncp    = require('ncp');         // cp -r
+var swig   = require('swig');        // Templating
+var extras = require('swig-extras'); // Moar templating
+var Q      = require('q');           // Promises
+
 var parser = require('./parser');
 var utils  = require('./utils');
 var logger = require('./log');
+
 extras.useFilter(swig, 'markdown');
+ncp.limit = 16;
 
@@ -49,2 +53,3 @@ /**
     /**
+     * Read a folder
      * @see {@link http://nodejs.org/api/fs.html#fs_fs_readdir_path_callback}
@@ -56,2 +61,3 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
     /**
+     * Create a folder
      * @see {@link http://nodejs.org/api/fs.html#fs_fs_mkdir_path_mode_callback}
@@ -61,4 +67,12 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
     create: Q.denodeify(fs.mkdir),
+
+    /**
+     * Copy a folder
+     * @see {@link https://github.com/AvianFlu/ncp}
+     * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
+     */
+    copy: Q.denodeify(ncp),
     
     /**
+     * Remove a folder
      * @see {@link https://github.com/isaacs/rimraf}
@@ -132,2 +146,3 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
     /**
+     * Read a file
      * @see {@link http://nodejs.org/api/fs.html#fs_fs_readfile_filename_options_callback}
@@ -139,2 +154,3 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
     /**
+     * Create a file
      * @see {@link http://nodejs.org/api/fs.html#fs_fs_writefile_filename_data_options_callback}
@@ -146,2 +162,3 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
     /**
+     * Remove a file
      * @see {@link http://nodejs.org/api/fs.html#fs_fs_unlink_path_callback}
@@ -161,12 +178,2 @@ * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
       });
-    },
-
-    /**
-     * Copy a file
-     * @param  {String} source
-     * @param  {String} destination
-     * @return {Q.Promise}
-     */
-    copy: function (source, destination) {
-      return fs.createReadStream(source).pipe(fs.createWriteStream(destination));
     }
@@ -190,7 +197,3 @@ },
   dumpAssets: function (destination) {
-    return exports.folder.create(destination + '/css').then(function () {
-      return exports.file.copy(__dirname + '/../assets/css/styles.css', destination + '/css/styles.css');
-    }, function (err) {
-      console.error(err);
-    });
+    return exports.folder.copy(__dirname + '/../assets', destination + '/assets');
   },
@@ -204,3 +207,3 @@
   generate: function (data, destination) {
-    var template = swig.compileFile(__dirname + '/../assets/templates/docs.html.swig');
+    var template = swig.compileFile(__dirname + '/../templates/docs.html.swig');
     
@@ -216,3 +219,5 @@ return exports.file.create(destination, template({ 'data': data }));
       var data = Data.fromArray(response);
-      exports.compileAliases(data);
+
+      exports.postTreatData(data);
+
       return exports.splitData(data.data.sort(function (a, b) {
@@ -241,14 +246,119 @@ if (a.name > b.name) return 1;
   /**
-   * Compile aliases for each function
+   * Post treat data to fill missing informations
+   * @param  {Object} data
    */
+  postTreatData: function (data) {
+    exports.compileAliases(data);
+    exports.compileRequires(data);
+    exports.raiseWarnings(data);
+  },
+
+  /**
+   * Compile aliases for each item
+   * @param {Object} data
+   */
   compileAliases: function (data) {
-    for (var item in data.index) {
-      if (!data.index[item].alias) {
+    var item, name;
+
+    for (name in data.index) {
+      item = data.index[name];
+
+      if (!item.alias) {
         continue;
       }
 
-      data.index[data.index[item].alias].aliased.push(item);
+      if (utils.isset(data.index[item.alias])) {
+        data.index[item.alias].aliased.push(item.name);
+      }
+
+      // Incorrect @alias
+      else {
+        logger.log("Item `" + name + " is an alias of `" + item.alias + "` but this item doesn't exist."); 
+      }
     }
+  },
+
+  /**
+   * Compile requires for each item
+   * @param {Object} data
+   */
+  compileRequires: function (data) {
+    var item, name;
+
+    for (name in data.index) {
+      item = data.index[name];
+
+      if (!utils.isset(item.requires)) {
+        continue;
+      }
+
+      for (var i = 0; i < item.requires.length; i++) {
+        if (utils.isset(item.requires[i].type)) {
+          continue;
+        } 
+
+        if (utils.isset(data.index[item.requires[i].item])) {
+          data.index[name].requires[i].type = data.index[item.requires[i].item].type;
+
+          // And fill `usedBy` key
+          if (!utils.isset(data.index[item.requires[i].item].usedBy)) {
+            data.index[item.requires[i].item].usedBy = [];
+          }
+
+          data.index[item.requires[i].item].usedBy.push({ 'item': item.name, 'type': item.type });
+        }
+
+        // Incorrect @requires
+        else {
+          logger.log("Item `" + name + " requires `" + item.requires[i].item + "` but this item doesn't exist.");
+        }
+      }
+    }
+  },
+
+  /**
+   * Raise warning for incoherent or invalid things
+   * @param {Object} data
+   */
+  raiseWarnings: function (data) {
+    var name, item, i;
+    var validTypes = ["*", "arglist", "bool", "color", "list", "map", "null", "number", "string"];
+    
+    if (logger.enabled === false) {
+      return;
+    }
+
+    for (name in data.index) {
+      item = data.index[name];
+
+      // Incorrect data type in @param
+      if (utils.isset(item.parameters)) {
+        for (i = 0; i < item.parameters.length; i++) {
+          if (validTypes.indexOf(item.parameters[i].type.toLowerCase()) === -1) {
+            logger.log("Parameter `" + item.parameters[i].name + "` from item `" + item.name + "` is from type `" + item.parameters[i].type + "` which is not a valid Sass type.");
+          }
+        }
+      }
+
+      // Incorrect data type in @return
+      if (utils.isset(item.returns) && item.returns.type) {
+        for (i = 0; i < item.returns.type.length; i++) {
+          if (validTypes.indexOf(item.returns.type[i].trim().toLowerCase()) === -1) {
+            logger.log("Item `" + item.name + "` can return a `" + item.returns.type[i] + "` which is not a valid Sass type.");
+          }
+        }
+      }
+
+      // Incorrect URL in @link
+      if (utils.isset(item.links)) {
+        for (i = 0; i < item.links.length; i++) {
+          if (!item.links[i].url.match(/https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)/)) {
+            logger.log("Item `" + item.name + "` has a link leading to an invalid URL (`" + item.links[i].url + "`).");
+          }
+        }
+      }
+
+    }
   }
 
 };

src/parser.js

@@ -210,3 +210,2 @@ 'use strict';
       case 'todos':
-      case 'requires':
         res.value = value[1];
@@ -216,2 +215,7 @@ res.array = true;
 
+      case 'requires':
+        res.value = { 'type': value[1], 'item': value[2] };
+        res.array = true;
+        break;
+     
       case 'link':
@@ -218,0 +222,0 @@ res.value = { 'url': value[1], 'caption': value[2] }

src/regex.js

@@ -161,3 +161,3 @@ 'use strict';
   isRequires: function (line) {
-    return line.match(/^@requires\s+([\w-]+)/i);
+    return line.match(/^@requires\s+(?:{(function|mixin|var)})?\s*([\w-]+)/i);
   },
@@ -164,0 +164,0 @@

src/utils.js

@@ -48,2 +48,11 @@ 'use strict';
     return line.trim().replace(/^\/{2,}/i, '').replace(/^\/?\*+\/?/i, '').trim();
+  },
+
+  /**
+   * Returns whether a value is set or not
+   * @param {*} value - value to check
+   * @return {Bool}
+   */
+  isset: function (value) {
+    return typeof value !== "undefined";
   }
@@ -50,0 +59,0 @@

No alert changes

Improved metrics

Total package byte prevSize

133581

4.68%

Lines of code

1297

8.54%

Number of lines in readme file

278

11.2%

Worsened metrics

Dependency count

6

20%

Dependency changes

• + Added

  ncp@^0.5.1

• + Added

  ncp@0.5.1
  (transitive)