fixes, tweaks, functionality

- Fixes
  - fixed incorrect default behavior which was to use all symbols.  now defaults to ignoring internal/private functions as before.  respects `@private` tag.
  - fixed problem wherein function-level `@description` would be duplicated in a `@returns` tag having no description of its own
  - fixed invalid `.jshintrc` and removed unused `jshint-config.json`
  - fixed bad formatting (extra comma) when displaying a member or parameter w/o a `@description`
- Enhancements
  - support for `@example` tag
  - support for `@property` tag
  - type support for both `@property` tag and members
- Display tweaks
  - separated `@author` tag display from `@license` tag display in template
  - types now display in `monospace`
  - class displays as title "Class: <classname>" to differentiate from module

.jshintrc

@@ -15,10 +15,6 @@
   "node": true,
   "noempty": true,
   "nonew": true,
-  "globals": {
-    "define": true,
-    "should": false
-  },
   "predef":
   [
     "after",
@@ -29,7 +25,8 @@
     "it",
     "unescape",
     "par",
-    "each"
+    "each",
+    "define"
   ],
   "smarttabs": true,
   "trailing": false,

jsdox.js

@@ -111,7 +111,7 @@ function generateForDir(filename, destination, templateDir, cb, fileCb) {
         console.log(file + ' Analyzed: ', util.inspect(analyze(result), false, 20));
       }
 
-      var data = analyze(result),
+      var data = analyze(result, argv),
           output = generateMD(data, templateDir);
 
       if (output) {
@@ -171,6 +171,7 @@ function loadConfigFile(file, callback){
   var config;
 
   //check to see if file exists
+  file = path.resolve(process.cwd(), file);
   fs.exists(file, function(exists) {
     if (exists) {
       try {

lib/analyze.js

@@ -2,6 +2,7 @@
  * Transforms the AST into a form that represents a single file with modules and their functions.
  *
  * @param {Object} ast
+ * @param {Object} argv Command-line args
  * @returns {Object}
  *
  * @example
@@ -44,7 +45,7 @@
  *   version: ''
  * }
  */
-module.exports = function(ast) {
+module.exports = function(ast, argv) {
   var result = {
     functions: [],
     methods: [],
@@ -62,7 +63,8 @@ module.exports = function(ast) {
   },
   currentModule   = null,
   currentClass    = null,
-  currentFunction = null;
+  currentFunction = null,
+  ignoreInternal = !argv.All;
 
   function initGlobalModule() {
     var global = {};
@@ -79,6 +81,7 @@ module.exports = function(ast) {
   }
 
   ast.forEach(function (tag) {
+    if (ignoreInternal && isInternal(tag)) { return; }
     switch (tag.kind) {
       case 'file':
         result.license   = tag.license;
@@ -103,14 +106,17 @@ module.exports = function(ast) {
         // For param details
         fn.params.forEach(setPipedTypesString);
         fn.returns      = tag.returns || [];
-        fn.returns.forEach(setPipedTypesString);
+        fn.returns.forEach(function(ret) {
+          setPipedTypesString(ret);
+          ret.description = ret.description || false;
+        });
         // To avoid reaching to the parent for these fields
         fn.version      = tag.version || false;
         fn.fires        = tag.fires || [];
         fn.description  = tag.description;
         fn.deprecated   = tag.deprecated || false;
-        fn.internal     = isInternal(fn.name);
         fn.moduleName   = currentModule ? currentModule.name : '';
+        fn.examples      = tag.examples || [];
         currentFunction = fn;
         if (currentClass) {
           currentClass.methods.push(fn);
@@ -133,6 +139,7 @@ module.exports = function(ast) {
       case 'member':
         if (currentClass && tag.undocumented !== true) {
           currentClass.members.push(tag);
+          setPipedTypesString(tag);
         } else if (tag.scope === 'inner' && tag.undocumented !== true) {
           result.members.push({member: tag.name});
           result.hasMembers = true;
@@ -148,6 +155,7 @@ module.exports = function(ast) {
       case 'module':
         var module = {};
         module.name = tag.name;
+        module.examples = tag.examples || [];
         module.functions = [];
         module.classes = [];
         module.description = tag.description;
@@ -164,8 +172,9 @@ module.exports = function(ast) {
         var klass = {};
         klass.name = tag.name;
         klass.methods = [];
-        klass.members = [];
         klass.description = tag.description;
+        klass.members = tag.properties || [];
+        klass.members.forEach(setPipedTypesString);
         result.classes.push(klass);
         if (currentModule) {
           currentModule.classes.push(klass);
@@ -194,6 +203,6 @@ function setPipedTypesString(node) {
   node.typesString = node.type.names.join(' | ');
 }
 
-function isInternal(name){
-  return name.lastIndexOf('_', 0) === 0;
+function isInternal(tag){
+  return tag && ((tag.name && tag.name.lastIndexOf('_', 0) === 0) || tag.private);
 }

package.json

@@ -33,7 +33,7 @@
     "lib"
   ],
   "scripts": {
-    "test": "jshint --config jshint-config.json jsdox.js bin/* test/* fixtures/* && node_modules/.bin/mocha;"
+    "test": "jshint --config .jshintrc jsdox.js bin/* test/* fixtures/* && node_modules/.bin/mocha;"
   },
   "preferGlobal": true,
   "bin": {

templates/class.mustache

@@ -5,8 +5,8 @@
 {{#description}}{{{description}}}{{/description}}
 
 {{#members}}
-**{{name}}** - {{{description}}}
+**{{name}}**: {{#typesString}}`{{typesString}}`{{/typesString}} {{#description}}, {{{description}}}{{/description}}  
 {{/members}}
 {{#methods}}
 {{> function}}
-{{/methods}}
+{{/methods}}

templates/file.mustache

@@ -22,14 +22,21 @@
 {{/members}}
 {{/hasMembers}}
 
+{{#examples}}
+**Example:**
+```js
+{{{examples}}}
+```
+
+{{/examples}}
 ---
 
 {{#functions}}
 {{> function}}
 
 {{/functions}}
 {{#classes}}
-{{> class}}
+Class: {{> class}}
 
 {{/classes}}
 
@@ -38,7 +45,9 @@
 
 {{#copyright}}*{{copyright}}*{{/copyright}}
 
-{{#license}}**License:** {{license}} {{/license}}{{#author}}{{author}}{{/author}}
+{{#author}}**Author:** {{author}}{{/author}}
+
+{{#license}}**License:** {{license}} {{/license}}
 
 {{#overview}}**Overview:** {{{overview}}}{{/overview}}
 

templates/function.mustache

@@ -13,13 +13,21 @@ Deprecated: {{{deprecated}}}
 
 {{/hasParams}}
 {{#params}}
-**{{name}}**: {{#typesString}}{{typesString}}, {{/typesString}}{{#description}}{{{description}}}{{/description}}
+**{{name}}**: {{#typesString}}`{{typesString}}`{{/typesString}}{{#description}}, {{{description}}}{{/description}}
 
 {{/params}}
 {{#fires}}
 **Fires**: {{.}}
 
 {{/fires}}
 {{#returns}}
-**Returns**: {{#typesString}}{{typesString}}, {{/typesString}}{{#description}}{{{description}}}{{/description}}
-{{/returns}}
+**Returns**: {{#typesString}}`{{typesString}}`{{/typesString}}{{#description}}, {{{description}}}{{/description}}
+{{/returns}}
+
+{{#examples}}
+**Example**:
+```js
+{{{examples}}}
+```
+
+{{/examples}}