fix(scopes): Support inner scope

declarations/comment.js

@@ -71,7 +71,9 @@ declare type CommentTag = {
 declare type CommentMembers = {
   static: Array<Comment>,
   instance: Array<Comment>,
-  events: Array<Comment>
+  events: Array<Comment>,
+  global: Array<Comment>,
+  inner: Array<Comment>
 };
 
 declare type CommentExample = {
@@ -84,6 +86,20 @@ declare type Remark = {
   children: Array<Object>
 };
 
+declare type Access = 'private' | 'public' | 'protected';
+declare type Scope = 'instance' | 'static' | 'inner' | 'global';
+declare type Kind = 'class' |
+  'constant' |
+  'event' |
+  'external' |
+  'file' |
+  'function' |
+  'member' |
+  'mixin' |
+  'module' |
+  'namespace' |
+  'typedef';
+
 declare type Comment = {
   errors: Array<CommentError>,
   tags: Array<CommentTag>,
@@ -106,10 +122,11 @@ declare type Comment = {
   members: CommentMembers,
 
   name?: string,
-  kind?: string,
+  kind?: Kind,
+
   memberof?: string,
-  scope?: string,
-  access?: string,
+  scope?: Scope,
+  access?: Access,
   alias?: string,
 
   copyright?: string,
@@ -126,6 +143,12 @@ declare type Comment = {
 
   path?: Array<{
     name: string,
-    scope: string
+    scope: Scope
   }>
 };
+
+declare type ReducedComment = {
+  name: string,
+  kind: ?Kind,
+  scope?: ?Scope
+}

default_theme/index._

@@ -56,6 +56,18 @@
                       <% }) %>
                     </ul>
                   <% } %>
+                  <% if (doc.members.inner && doc.members.inner.length) { %>
+                    <ul class='list-reset py1-ul pl1'>
+                      <li class='h5'><span>Inner members</span></li>
+                      <% doc.members.inner.forEach(function(member) { %>
+                      <li><a
+                        href='#<%=member.namespace%>'
+                        class='regular pre-open'>
+                        #<%- member.name %>
+                      </a></li>
+                      <% }) %>
+                    </ul>
+                  <% } %>
                   <% if (doc.members.events && doc.members.events.length) { %>
                     <ul class='list-reset py1-ul pl1'>
                       <li class='h5'>Events</li>

lib/hierarchy.js

@@ -10,12 +10,18 @@ var hasOwnProperty = Object.prototype.hasOwnProperty;
  */
 let isEvent = member => member.kind === 'event';
 
-/*::
-declare type ReducedComment = {
-  name: string,
-  kind: ?string,
-  scope?: ?string
-} */
+/**
+ * We need to have members of all valid JSDoc scopes.
+ * @private
+ */
+let getMembers = () => ({
+  global: Object.create(null),
+  inner: Object.create(null),
+  instance: Object.create(null),
+  events: Object.create(null),
+  static: Object.create(null)
+});
+
 
 /**
  * Pick only relevant properties from a comment to store them in
@@ -49,12 +55,10 @@ function pick(comment/*: Comment */)/*: ?ReducedComment */ {
 module.exports = function (comments/*: Array<Comment>*/) {
   var id = 0,
     root = {
-      members: {
-        instance: Object.create(null),
-        static: Object.create(null)
-      }
+      members: getMembers()
     };
 
+
   comments.forEach(comment => {
     var path = [];
 
@@ -86,10 +90,7 @@ module.exports = function (comments/*: Array<Comment>*/) {
       if (!hasOwnProperty.call(node.members[scope], name)) {
         node.members[scope][name] = {
           comments: [],
-          members: {
-            instance: Object.create(null),
-            static: Object.create(null)
-          }
+          members: getMembers()
         };
       }
 
@@ -138,7 +139,7 @@ module.exports = function (comments/*: Array<Comment>*/) {
           comment.members[scope] = node.members[scope];
         }
 
-        var events = comment.members.events || [];
+        var events = comment.members.events;
         var groups = [];
 
         if (comment.members.instance.length) {
@@ -155,6 +156,20 @@ module.exports = function (comments/*: Array<Comment>*/) {
           comment.members.static = groups[false] || [];
         }
 
+        if (comment.members.inner.length) {
+          groups = _.groupBy(comment.members.inner, isEvent);
+
+          events = events.concat(groups[true] || []);
+          comment.members.inner = groups[false] || [];
+        }
+
+        if (comment.members.global.length) {
+          groups = _.groupBy(comment.members.global, isEvent);
+
+          events = events.concat(groups[true] || []);
+          comment.members.global = groups[false] || [];
+        }
+
         comment.members.events = events;
 
         comment.path = path.map(pick)
@@ -163,7 +178,9 @@ module.exports = function (comments/*: Array<Comment>*/) {
 
         var scopeChars = {
           instance: '#',
-          static: '.'
+          static: '.',
+          inner: '~',
+          global: ''
         };
 
         comment.namespace = comment.path.reduce((memo, part) => {

lib/output/markdown_ast.js

@@ -212,12 +212,18 @@ function buildMarkdownAST(comments/*: Array<Comment> */, config/*: Documentation
     .concat(throwsSection(comment))
     .concat(returnsSection(comment))
     .concat(metaSection(comment))
+    .concat(!!comment.members.global.length &&
+      comment.members.global.reduce((memo, child) =>
+        memo.concat(generate(depth + 1, child)), []))
     .concat(!!comment.members.instance.length &&
       comment.members.instance.reduce((memo, child) =>
         memo.concat(generate(depth + 1, child)), []))
     .concat(!!comment.members.static.length &&
       comment.members.static.reduce((memo, child) =>
         memo.concat(generate(depth + 1, child)), []))
+    .concat(!!comment.members.inner.length &&
+      comment.members.inner.reduce((memo, child) =>
+        memo.concat(generate(depth + 1, child)), []))
     .filter(Boolean);
   }
 

lib/parse.js

@@ -21,6 +21,7 @@ var flatteners = {
    * @returns {undefined} has side-effects
    */
   'access': function (result, tag) {
+    // doctrine ensures that tag.access is valid
     result.access = tag.access;
   },
   'alias': flattenName,
@@ -208,6 +209,7 @@ var flatteners = {
    * @returns {undefined} has side-effects
    */
   'kind': function (result, tag) {
+    // doctrine ensures that tag.kind is valid
     result.kind = tag.kind;
   },
   'lends': flattenDescription,

lib/serve/error_page.js

@@ -1,4 +1,5 @@
 /* @flow */
+/* eslint no-console: 0 */
 'use strict';
 var File = require('vinyl');
 var ansiHTML = require('ansi-html');

test/fixture/_external-deps-included.json

@@ -121,9 +121,11 @@
     "name": "foo",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {
@@ -291,9 +293,11 @@
     "name": "main",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {
@@ -461,9 +465,11 @@
     "name": "index",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {

test/fixture/_multi-file-input.json

@@ -238,9 +238,11 @@
     "name": "returnTwo",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {
@@ -408,9 +410,11 @@
     "name": "simple.input",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {

test/fixture/boolean-literal-type.output.json

@@ -72,9 +72,11 @@
     "name": "f",
     "kind": "function",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {

test/fixture/class.output.json

@@ -167,6 +167,8 @@
     "kind": "class",
     "name": "MyClass",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [
         {
           "description": {
@@ -400,9 +402,11 @@
           "memberof": "MyClass",
           "scope": "instance",
           "members": {
+            "global": [],
+            "inner": [],
             "instance": [],
-            "static": [],
-            "events": []
+            "events": [],
+            "static": []
           },
           "path": [
             {
@@ -575,9 +579,11 @@
           "memberof": "MyClass",
           "scope": "instance",
           "members": {
+            "global": [],
+            "inner": [],
             "instance": [],
-            "static": [],
-            "events": []
+            "events": [],
+            "static": []
           },
           "path": [
             {
@@ -593,8 +599,8 @@
           "namespace": "MyClass#getUndefined"
         }
       ],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {

test/fixture/document-exported-export-default-object.output.json

@@ -35,9 +35,11 @@
     "todos": [],
     "name": "document-exported-export-default-object.input",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {
@@ -82,9 +84,11 @@
     "todos": [],
     "name": "x",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {

test/fixture/document-exported-export-default-value.output.json

@@ -35,9 +35,11 @@
     "todos": [],
     "name": "document-exported-export-default-value.input",
     "members": {
+      "global": [],
+      "inner": [],
       "instance": [],
-      "static": [],
-      "events": []
+      "events": [],
+      "static": []
     },
     "path": [
       {