dox - npm Package Compare versions

Comparing version 0.4.4 to 0.4.5

History.md

@@ -0,2 +1,9 @@
+0.4.5 / 2014-07-09
+==================
 
+ * use marked for markdown rendering
+ * multiline tags support (@example)
+ * support for @template, @property, @define, @public, @private, @protected,
+   @lends, @extends, @implements, @enum, @typedef
+
 0.4.4 / 2013-07-28 
@@ -3,0 +10,0 @@ ==================

lib/dox.js

@@ -5,5 +5,30 @@ /*!
 
-var markdown = require('github-flavored-markdown').parse
+var markdown = require('marked')
   , escape = require('./utils').escape;
 
+var renderer = new markdown.Renderer();
+
+renderer.heading = function (text, level) {
+  return '<h' + level + '>' + text + '</h' + level + '>\n';
+};
+
+renderer.paragraph = function (text) {
+  return '<p>' + text + '</p>';
+};
+
+renderer.br = function () {
+  return '<br />';
+};
+
+markdown.setOptions({
+  renderer: renderer
+, gfm: true
+, tables: true
+, breaks: true
+, pedantic: false
+, sanitize: false
+, smartLists: true
+, smartypants: false
+});
+
 /**
@@ -117,6 +142,7 @@ * Expose api.
     , raw = options.raw
-    , description = {};
+    , description = {}
+    , tags = str.split('\n@');
 
   // parse comment body
-  description.full = str.split('\n@')[0];
+  description.full = tags[0];
   description.summary = description.full.split('\n\n')[0];
@@ -127,8 +153,9 @@ description.body = description.full.split('\n\n').slice(1).join('\n\n');
   // parse tags
-  if (~str.indexOf('\n@')) {
-    var tags = '@' + str.split('\n@').slice(1).join('\n@');
-    comment.tags = tags.split('\n').map(exports.parseTag);
+  if (tags.length) {
+    comment.tags = tags.slice(1).map(function(str) {
+      return exports.parseTag(str, raw)
+    });
     comment.isPrivate = comment.tags.some(function(tag){
-      return 'api' == tag.type && 'private' == tag.visibility;
-    })
+      return 'private' == tag.visibility;
+    });
   }
@@ -150,2 +177,3 @@
  * @param {String}
+ * @param {boolean} raw
  * @return {Object}
@@ -155,8 +183,15 @@ * @api public
 
-exports.parseTag = function(str) {
+exports.parseTag = function(str, raw) {
   var tag = {}
-    , parts = str.split(/ +/)
+    , lines = str.split('\n')
+    , parts = lines[0].split(/ +/)
     , type = tag.type = parts.shift().replace('@', '');
 
+  if (lines.length > 1) {
+    parts.push(lines.slice(1).join('\n'));
+  }
+
   switch (type) {
+    case 'property':
+    case 'template':
     case 'param':
@@ -167,2 +202,3 @@ tag.types = exports.parseTagTypes(parts.shift());
       break;
+    case 'define':
     case 'return':
@@ -181,11 +217,22 @@ tag.types = exports.parseTagTypes(parts.shift());
       }
+      break;
     case 'api':
       tag.visibility = parts.shift();
       break;
+    case 'public':
+    case 'private':
+    case 'protected':
+      tag.visibility = type;
+      break;
+    case 'enum':
+    case 'typedef':
     case 'type':
       tag.types = exports.parseTagTypes(parts.shift());
       break;
+    case 'lends':
     case 'memberOf':
       tag.parent = parts.shift();
       break;
+    case 'extends':
+    case 'implements':
     case 'augments':
@@ -202,2 +249,5 @@ tag.otherClass = parts.shift();
       break;
+    case 'example':
+      tag.string = raw ? parts.join(' ') : markdown(parts.join(' '));
+      break;
     default:
@@ -204,0 +254,0 @@ tag.string = parts.join(' ');

package.json

 {   "name": "dox"
   , "description": "Markdown / JSdoc documentation generator"
-  , "version": "0.4.4"
+  , "version": "0.4.5"
   , "author": "TJ Holowaychuk <[e-mail]>"
@@ -9,9 +9,12 @@ , "repository": { "type": "git", "url": "git://github.com/visionmedia/dox.git" }
   , "dependencies": {
-      "github-flavored-markdown": ">= 0.0.1"
+      "marked": ">=0.3.1"
     , "commander": "0.6.1"
   }
   , "devDependencies": {
-      "mocha": "*"
-    , "should": "*"
+      "mocha": "^1.20.1"
+    , "should": "^4.0.4"
   }
+  , "scripts": {
+    "test": "make test"
+  }
 }

Readme.md

 # Dox
+[![build status](https://secure.travis-ci.org/visionmedia/dox.png)](http://travis-ci.org/visionmedia/dox)
 
@@ -16,8 +17,8 @@ Dox is a JavaScript documentation generator written with [node](http://nodejs.org). Dox no longer generates an opinionated structure or style for your docs, it simply gives you a JSON representation, allowing you to use _markdown_ and _JSDoc_-style tags.
     $ dox < utils.js
-    ...JSON... 
+    ...JSON...
 
  to inspect the generated data you can use the `--debug` flag, which is easier to read than the JSON output:
- 
-     $ dox --debug < utils.js 
 
+     $ dox --debug < utils.js
+
 utils.js:
@@ -29,4 +30,3 @@
  *
- * Examples:
- *
+ * @example
  *     utils.escape('<script></script>')
@@ -55,2 +55,6 @@ *     // => '&lt;script&gt;&lt;/script&gt;'
       {
+        "type": "example",
+        "string": "<pre><code>utils.escape(&#39;&lt;script&gt;&lt;/script&gt;&#39;)\n// =&gt; &#39;&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;&#39;\n</code></pre>"
+      },
+      {
         "type": "param",
@@ -76,5 +80,5 @@ "types": [
     "description": {
-      "full": "<p>Escape the given <code>html</code>.</p>\n\n<h2>Examples</h2>\n\n<pre><code>utils.escape('&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;')\n// =&amp;gt; '&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;'\n</code></pre>",
+      "full": "<p>Escape the given <code>html</code>.</p>",
       "summary": "<p>Escape the given <code>html</code>.</p>",
-      "body": "<h2>Examples</h2>\n\n<pre><code>utils.escape('&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;')\n// =&amp;gt; '&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;'\n</code></pre>"
+      "body": ""
     },
@@ -121,3 +125,3 @@ "isPrivate": false,
   A "comment" is comprised of the following detailed properties:
-  
+
     - tags
@@ -149,3 +153,3 @@ - description
 ```js
-description: 
+description:
      { full: '<p>Output the given <code>str</code> to <em>stdout</em>.</p>',
@@ -162,12 +166,12 @@ summary: '<p>Output the given <code>str</code> to <em>stdout</em>.</p>',
  * or the stream specified by `options`.
- * 
+ *
  * Options:
- * 
+ *
  *   - `stream` defaulting to _stdout_
- * 
+ *
  * Examples:
- * 
+ *
  *     mymodule.write('foo')
  *     mymodule.write('foo', { stream: process.stderr })
- * 
+ *
  */
@@ -184,3 +188,3 @@
 ```js
-description: 
+description:
      { full: '<p>Output the given <code>str</code> to <em>stdout</em><br />or the stream specified by <code>options</code>.</p>\n\n<h2>Options</h2>\n\n<ul>\n<li><code>stream</code> defaulting to <em>stdout</em></li>\n</ul>\n\n<h2>Examples</h2>\n\n<pre><code>mymodule.write(\'foo\')\nmymodule.write(\'foo\', { stream: process.stderr })\n</code></pre>',
@@ -200,3 +204,3 @@ summary: '<p>Output the given <code>str</code> to <em>stdout</em><br />or the stream specified by <code>options</code>.</p>',
  * or the stream specified by `options`.
- * 
+ *
  * @param {String} str
@@ -217,3 +221,3 @@ * @param {Object} options
 ```js
-tags: 
+tags:
    [ { type: 'param',
@@ -258,3 +262,3 @@ types: [ 'String' ],
 ```js
-ctx: 
+ctx:
  { type: 'method',
@@ -273,3 +277,3 @@ receiver: 'exports',
 ```js
-ctx: 
+ctx:
  { type: 'declaration',
@@ -283,3 +287,3 @@ name: 'foo',
 function User() {
-  
+
 }
@@ -291,3 +295,3 @@ ```
 ```js
-ctx: 
+ctx:
  { type: 'function',
@@ -319,7 +323,7 @@ name: 'User',
  Install dev dependencies and execute `make test`:
- 
+
      $ npm install -d
      $ make test
 
-## License 
+## License
 
@@ -347,2 +351,2 @@ (The MIT License)
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

22804

increased by5.45%

Number of package files

12

increased by9.09%

Lines of code

388

increased by12.79%

Number of lines in readme file

337

increased by1.51%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedmarked@>=0.3.1

• + Addedmarked@15.0.0(transitive)

• - Removedgithub-flavored-markdown@>= 0.0.1

• - Removedgithub-flavored-markdown@1.0.1(transitive)