Merge 02f417f into 003bed2

.gitignore

@@ -29,4 +29,5 @@ selection.json
 # runtime junk
 npm-debug.log
 /examples/*/public
-/megadoc.sublime-workspace
+/megadoc.sublime-workspace
+/.local

doc/megadoc.conf.js

@@ -162,7 +162,7 @@ config.plugins = [
       'ui/**/*.js',
     ],
 
-    exclude: [ /test/, /vendor/, ],
+    exclude: [ /__tests__/, /vendor/, ],
 
     useDirAsNamespace: false,
 

karma.main.js

@@ -9,14 +9,18 @@ require('./ui');
 
 sinon.assert.expose(chai.assert, { prefix: "" });
 
-const CoreUITests = require.context('./ui', true, /.test.js$/);
-
-CoreUITests.keys().forEach(CoreUITests);
+tap(require.context('./ui', true, /.test.js$/), function(x) {
+  x.keys().forEach(x);
+});
 
 tap(require.context('./packages/megadoc-plugin-markdown/ui', true, /.test.js$/), function(x) {
   x.keys().forEach(x);
 });
 
+tap(require.context('./packages/megadoc-plugin-js/ui', true, /.test.js$/), function(x) {
+  x.keys().forEach(x);
+});
+
 it('gives us something', function() {
   chai.assert.ok(true);
 });

lib/HTMLSerializer__LinkResolver.js

@@ -1,6 +1,7 @@
 var assert = require('assert');
 var EventEmitter = require('events').EventEmitter;
 var URI = require('urijs');
+var dumpNodeFilePath = require('megadoc-corpus').Corpus.dumpNodeFilePath;
 
 /**
  * @param {Corpus} corpus
@@ -44,10 +45,15 @@ LinkResolver.prototype.lookup = function(params) {
   assert(typeof params.path === 'string',
     "A lookup requires at least a @path to be specified.");
 
+  if (params.path.length === 0) {
+    console.warn("Link seems to be empty... Source:", dumpNodeFilePath(params.contextNode));
+    return;
+  }
+
   if (process.env.VERBOSE) {
     console.log('Resolving link to "%s" from "%s"...',
       params.path,
-      params.contextNode ? params.contextNode.uid : '<<unknown>>'
+      dumpNodeFilePath(params.contextNode)
     );
   }
 

lib/Renderer__renderCode.js

@@ -3,6 +3,7 @@ var assign = require('lodash').assign;
 
 function CodeRenderer(userConfig) {
   var config = assign({
+    defaultLanguage: null,
     languages: [],
     aliases: {}
   }, userConfig);
@@ -19,7 +20,7 @@ function CodeRenderer(userConfig) {
   });
 
   return function renderCode(code, language) {
-    var languageCode = config.aliases[language] || language;
+    var languageCode = config.aliases[language] || language || config.defaultLanguage;
     var grammar = Prism.languages[languageCode];
     var html = code;
 

lib/Renderer__renderHeading.js

@@ -26,6 +26,10 @@ function renderHeading(text, level, state, runOptions) {
 
   var id = state.baseURL ? joinBySlash(state.baseURL, scopedId) : scopedId;
 
+  if (state.toc.some(function(x) { return x.scopedId === scopedId; })) {
+    scopedId = level + scopedId;
+  }
+
   // TODO: gief a markdown analyzer, really...
   state.toc.push({
     id: id,

lib/config.js

@@ -266,6 +266,8 @@ module.exports = {
    * [Prism.js](http://prismjs.com/).
    */
   syntaxHighlighting: {
+    defaultLanguage: 'javascript',
+
     /**
      * @property {Array.<String>} syntaxHighlighting.languages
      *

package.json

@@ -32,9 +32,9 @@
   "homepage": "https://github.com/megadoc/megadoc",
   "dependencies": {
     "async": "^2.0.0-rc.3",
-    "babel-core": "6.7.6",
+    "babel-core": "6.9.0",
     "babel-loader": "6.2.4",
-    "babel-preset-es2015": "6.6.0",
+    "babel-preset-es2015": "6.9.0",
     "babel-preset-react": "6.5.0",
     "classnames": "^2.1.5",
     "commander": "^2.8.1",
@@ -82,7 +82,7 @@
     "karma-mocha": "0.1.10",
     "karma-sourcemap-loader": "0.3.3",
     "karma-webpack": "1.7.0",
-    "mocha": "^2.3.3",
+    "mocha": "2.4.5",
     "mocha-lcov-reporter": "^1.0.0",
     "react-drill": "2.1.1",
     "react-hot-loader": "1.3.0",

packages/megadoc-corpus/defs/core.js

@@ -30,7 +30,6 @@ var t = CorpusTypes.builtInTypes;
  * });
  * ```
  */
-var exports;
 
 /**
  * @module T.Corpus
@@ -73,7 +72,7 @@ def("Corpus", {
 def("Namespace", {
   fields: {
     /**
-     * @property {String}
+     * @property {!String}
      *
      * An identifier for this namespace that must be unique at this level in the
      * corpus. The identifier is utilized in the generation of [CorpusUIDs UIDs]()
@@ -83,7 +82,7 @@ def("Namespace", {
     id: t.string,
 
     /**
-     * @property {String}
+     * @property {!String}
      *
      * A name to be used internally for the namespace. This property is meant to
      * identify the "class" of the namespace; or in other words, the type of
@@ -99,7 +98,7 @@ def("Namespace", {
     name: t.string,
 
     /**
-     * @property {String} [title=null]
+     * @property {String?} [title=null]
      *
      * A human-friendly title for display for this namespace. The title will be
      * utilized in the UI any time we need to reference this namespace, like in
@@ -112,7 +111,7 @@ def("Namespace", {
     title: or(t.string, null),
 
     /**
-     * @property {String} [symbol]
+     * @property {String?} [symbol="/"]
      *
      * The symbol is used when generating [[UIDs | CorpusUIDs]] for documents
      * in the namespace; their UID will effectively be their [[T.Node@id]]
@@ -129,8 +128,6 @@ def("Namespace", {
      * ```
      *
      * Document A above will have a UID of `X/A`.
-     *
-     * _Defaults to: `/`_
      */
     symbol: or(t.string, null),
 
@@ -214,6 +211,8 @@ def("Node", {
      */
     filePath: or(t.string, null),
 
+    loc: or(t.object, null),
+
     /**
      * @inheritdoc T.Corpus@meta
      */

packages/megadoc-corpus/lib/Corpus.js

@@ -184,8 +184,8 @@ function Corpus() {
     if (node.uid in nodes) {
       assert(false,
         'IntegrityViolation: a node with the UID "' + node.uid + '" already exists.' +
-        '\nOriginal node is defined in: ' + (nodes[node.uid].filePath || '<<unknown>>') +
-        '\nCurrent node is defined in: ' + (node.filePath || '<<unknown>>')
+        '\nPast definition: ' + dumpNodeFilePath(nodes[node.uid]) +
+        '\nThis definition: ' + dumpNodeFilePath(node)
       );
     }
 
@@ -269,5 +269,19 @@ function hasValidNamespaceId(node) {
   return node.id && node.id[0] !== '/' && node.id[0] !== '.';
 }
 
-module.exports = Corpus;
+function dumpNodeFilePath(node) {
+  var buffer = '<<unknown>>';
+
+  if (node && node.filePath) {
+    buffer = node.filePath;
+
+    if (node.loc && node.loc.start && node.loc.start.line) {
+      buffer += ':' + node.loc.start.line;
+    }
+  }
+
+  return buffer;
+}
 
+module.exports = Corpus;
+module.exports.dumpNodeFilePath = dumpNodeFilePath;

packages/megadoc-corpus/lib/CorpusResolver.js

@@ -162,7 +162,7 @@ function resolveByFilePath(anchor) {
     filePath = filePath.slice(0, -1 * entityId.length);
   }
 
-  targetPath = path.join(path.dirname(contextNode.filePath), filePath);
+  targetPath = ensureLeadingSlash(path.join(path.dirname(contextNode.filePath), filePath));
 
   var node = resolve({ text: targetPath, contextNode: anchor.contextNode });
 
@@ -191,4 +191,8 @@ function createListOfFriendNodes(node) {
   }
 
   return map;
+}
+
+function ensureLeadingSlash(s) {
+  return s[0] === '/' ? s : '/' + s;
 }

packages/megadoc-docstring/lib/utils/__tests__/neutralizeWhitespace.test.js

@@ -63,4 +63,24 @@ describe('utils::neutralizeWhitespace', function() {
 
     assert.deepEqual(input, output);
   });
+
+  it('strips leading whitespace from description', function() {
+    var string = multiline(function() {;
+      //          This
+      //          is
+      //          a
+      //          multiline
+      //          description.
+    });
+
+    assert.equal(
+      neutralizeWhitespace(string)
+        // this silly hack is to work around istanbul's instrumentor /
+        // multiline-slash where when NOT instrumenting, we'll have a leading
+        // newline
+        .replace(/^\n{0,1}/, '')
+      ,
+      'This\nis\na\nmultiline\ndescription.\n    '
+    );
+  });
 });

packages/megadoc-docstring/lib/utils/neutralizeWhitespace.js

@@ -9,7 +9,7 @@ var RE_MATCH_INDENT = /(?:^|\n)([ \t]*)[^\s]/;
  * @param {String} str
  * @return {String}
  */
-module.exports = function(src) {
+module.exports = function neutralizeWhitespace(src) {
   var indent = src.match(RE_MATCH_INDENT);
   if (indent && indent[1].length !== CODE_BLOCK_PADDING) {
     return src.replace(new RegExp('(^|\n)' + indent[1], 'g'), '$1');

packages/megadoc-docstring/package.json

@@ -29,8 +29,5 @@
   "homepage": "https://github.com/megadoc/megadoc#readme",
   "dependencies": {
     "jsdoctypeparser": "1.2.0"
-  },
-  "devDependencies": {
-    "pegjs": "0.9.0"
   }
 }

packages/megadoc-plugin-js/lib/Parser/Utils.js → packages/megadoc-plugin-js/lib/Parser/ASTUtils.js

@@ -1,16 +1,17 @@
 var nodejsPath = require('path');
 var t = require('babel-types');
+var K = require('./constants');
+var DocUtils = require('./DocUtils');
 
 var Utils = exports;
 
 Utils.isModuleExports = function(node) {
   return (
-    t.isMemberExpression(node.left)
-    && node.left.object.name === 'module'
-    && node.left.property.name === 'exports'
-    && (
-      t.isIdentifier(node.right)
-      || t.isFunctionExpression(node.right)
+    t.isMemberExpression(node.left) &&
+    node.left.object.name === 'module' &&
+    node.left.property.name === 'exports' && (
+      t.isIdentifier(node.right) ||
+      t.isFunctionExpression(node.right)
     )
   );
 };
@@ -40,13 +41,14 @@ Utils.isInstanceEntity = function(node) {
 };
 
 Utils.isFactoryModuleReturnEntity = function(node, startingPath, registry) {
+
   var modulePath = Utils.findAncestorPath(startingPath, function(path) {
     var doc = registry.getModuleDocAtPath(path);
 
     return (
       doc &&
       doc.isModule() &&
-      doc.nodeInfo.ctx.type === 'function'
+      DocUtils.isOfType(doc, K.TYPE_FUNCTION)
     );
   });
 
@@ -101,7 +103,7 @@ Utils.findScope = function(path) {
 
   do {
     scope = path.scope;
-  } while (!scope && path && (path = path.parentPath));
+  } while (!scope && ((path = path.parentPath)));
 
   return scope;
 };
@@ -114,7 +116,7 @@ Utils.findNearestPathWithComments = function(startingPath) {
 };
 
 Utils.dumpLocation = function(node, filePath) {
-  return [filePath, node.loc.start.line].join(':');
+  return [filePath, Utils.getLocation(node).start.line].join(':');
 };
 
 /**
@@ -133,16 +135,7 @@ Utils.findIdentifierInScope = function(identifierName, path) {
   if (currentScope) {
     var targetScope = currentScope.getBinding(identifierName);
 
-    // for (var x in currentScope) {
-    //   if (typeof currentScope[x] === 'function')
-    //     console.log('#' + x);
-    // }
     return targetScope && targetScope.path;
-    // console.log(targetScope)
-    // if (targetScope) {
-    //   console.log(targetScope)
-    //   return targetScope.getBinding(identifierName)[0];
-    // }
   }
 };
 
@@ -156,5 +149,28 @@ Utils.getLocation = function(node) {
     loc = node.loc;
   }
 
-  return loc || { start: {}, end: {} };
-};
+  return loc || {
+    start: { line: '?' },
+    end: { line: '?' }
+  };
+};
+
+// Whether there's a commenet for such a node:
+//
+//     /**
+//      * @module
+//      */
+//      var { Assertion } = require('chai');
+//
+Utils.isCommentedDestructuredProperty = function(path) {
+  return (
+    t.isIdentifier(path.node) &&
+    path.node.leadingComments &&
+    path.parentPath &&
+    t.isVariableDeclarator(path.parentPath) &&
+    path.parentPath.parentPath &&
+    t.isVariableDeclaration(path.parentPath.parentPath) &&
+    path.parentPath.parentPath.node.leadingComments &&
+    path.parentPath.parentPath.node.leadingComments[0] === path.node.leadingComments[0]
+  );
+};