CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+<a name="4.0.0-rc.0"></a>
+# [4.0.0-rc.0](https://github.com/documentationjs/documentation/compare/v4.0.0-beta.19...v4.0.0-rc.0) (2017-04-21)
+
+
+### Bug Fixes
+
+* **html output:** Fix github links in HTML output ([#745](https://github.com/documentationjs/documentation/issues/745)) ([9554b2f](https://github.com/documentationjs/documentation/commit/9554b2f)), closes [#738](https://github.com/documentationjs/documentation/issues/738)
+* **params:** added code path for type RestElement ([6961ee8](https://github.com/documentationjs/documentation/commit/6961ee8))
+
+
+### Code Refactoring
+
+* **nest:** Better nesting implementation ([#732](https://github.com/documentationjs/documentation/issues/732)) ([7374730](https://github.com/documentationjs/documentation/commit/7374730))
+
+
+### BREAKING CHANGES
+
+* **nest:** referencing inferred destructure params without
+renaming them, like $0.x, from JSDoc comments will no longer
+work. To reference them, instead add a param tag to name the
+destructuring param, and then refer to members of that name.
+
+Before:
+
+```js
+/**
+ * @param {number} $0.x a member of x
+ */
+function a({ x }) {}
+```
+
+After:
+
+```js
+/**
+ * @param {Object} options
+ * @param {number} options.x a member of x
+ */
+function a({ x }) {}
+```
+
+* Address review comments
+
+* Reduce testing node requirement back down to 4
+
+* Don't output empty properties, reduce diff noise
+
+* Rearrange and document params
+
+* Simplify param inference, update test fixtures. This is focused around Array destructuring: documenting destructured array elements with indices instead of names, because the names are purely internal details
+
+* Use temporary fork to get through blocker
+
+
+
 <a name="4.0.0-beta.19"></a>
 # [4.0.0-beta.19](https://github.com/documentationjs/documentation/compare/v4.0.0-beta.18...v4.0.0-beta.19) (2017-04-10)
 

declarations/comment.js

@@ -1,9 +1,10 @@
-declare type DocumentationConfig = {
+type DocumentationConfig = {
   polyglot?: boolean,
-  inferPrivate?: boolean,
+  inferPrivate?: string,
   noPackage?: boolean,
   toc?: Array<Object>,
   paths?: { [key: string]: number },
+  access?: Array<string>,
   defaultGlobals?: boolean,
   defaultGlobalsEnvs?: Array<string>,
   external?: Array<string>,
@@ -12,25 +13,25 @@ declare type DocumentationConfig = {
   parseExtension: Array<string>
 };
 
-declare type InputsConfig = {
+type InputsConfig = {
   inputs: Array<SourceFile>,
   config: DocumentationConfig
 };
 
-declare type CommentError = {
+type CommentError = {
   message: string,
   commentLineNumber?: number
 };
 
-declare type DoctrineType = {
+type DoctrineType = {
   elements?: Array<DoctrineType>,
   expression?: DoctrineType,
   applications?: Array<DoctrineType>,
   type: string,
   name?: string
 };
 
-declare type CommentLoc = {
+type CommentLoc = {
   start: {
     line: number
   },
@@ -39,12 +40,12 @@ declare type CommentLoc = {
   }
 };
 
-declare type SourceFile = {
+type SourceFile = {
   source?: string,
   file: string
 };
 
-declare type CommentContext = {
+type CommentContext = {
   sortKey: string,
   file: string,
   ast: Object,
@@ -53,12 +54,26 @@ declare type CommentContext = {
   github?: CommentContextGitHub
 };
 
-declare type CommentContextGitHub = {
+type CommentContextGitHub = {
   path: string,
   url: string
 };
 
-declare type CommentTag = {
+type CommentTagBase = {
+  title: string
+};
+
+type CommentTag = CommentTagBase & {
+  name?: string,
+  title: string,
+  description?: Object,
+  default?: any,
+  lineNumber?: number,
+  type?: DoctrineType,
+  properties?: Array<CommentTag>
+};
+
+type CommentTagNamed = CommentTag & {
   name?: string,
   title: string,
   description?: Object,
@@ -68,40 +83,41 @@ declare type CommentTag = {
   properties?: Array<CommentTag>
 };
 
-declare type CommentMembers = {
+type CommentMembers = {
   static: Array<Comment>,
   instance: Array<Comment>,
   events: Array<Comment>,
   global: Array<Comment>,
   inner: Array<Comment>
 };
 
-declare type CommentExample = {
+type CommentExample = {
   caption?: string,
   description?: Object
 };
 
-declare type Remark = {
+type Remark = {
   type: string,
   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' |
-  'interface';
-
-declare type Comment = {
+type Access = 'private' | 'public' | 'protected';
+type Scope = 'instance' | 'static' | 'inner' | 'global';
+type Kind =
+  | 'class'
+  | 'constant'
+  | 'event'
+  | 'external'
+  | 'file'
+  | 'function'
+  | 'member'
+  | 'mixin'
+  | 'module'
+  | 'namespace'
+  | 'typedef'
+  | 'interface';
+
+type Comment = {
   errors: Array<CommentError>,
   tags: Array<CommentTag>,
 
@@ -148,8 +164,8 @@ declare type Comment = {
   }>
 };
 
-declare type ReducedComment = {
+type ReducedComment = {
   name: string,
   kind: ?Kind,
   scope?: ?Scope
-}
+};

default_theme/section._

@@ -8,8 +8,8 @@
     </h3>
     <% } %>
     <% if (section.context && section.context.github) { %>
-      <a class='fr fill-darken0 round round pad1x quiet h5' href='<%= section.context.github %>'>
-      <span><%= section.context.path %></span>
+      <a class='fr fill-darken0 round round pad1x quiet h5' href='<%= section.context.github.url %>'>
+      <span><%= section.context.github.path %></span>
       </a>
     <% } %>
   </div>
@@ -52,7 +52,7 @@
             = <code><%- param.default %></code><% } %>)</code>
 	    <%= md(param.description, true) %>
           </div>
-          <% if (param.properties) { %>
+          <% if (param.properties && param.properties.length) { %>
           <table class='mt1 mb2 fixed-table h5 col-12'>
             <colgroup>
               <col width='30%' />
@@ -93,7 +93,7 @@
           <% } %><% if (property.description) {
 	    %>: <%= md(property.description, true) %><%
 	  } %>
-          <% if (property.properties) { %>
+          <% if (property.properties && property.properties.length) { %>
             <ul>
               <% property.properties.forEach(function(property) { %>
                 <li><code><%- property.name %></code> <%= formatType(property.type) %>

lib/extractors/exported.js

@@ -28,7 +28,7 @@ function walkExported(
 ) {
   var newResults = [];
   var filename = data.file;
-  var dataCache = Object.create(null);
+  var dataCache = new Map();
 
   function addBlankComment(data, path, node) {
     return addComment(data, '', node.loc, path, node.loc, true);
@@ -178,7 +178,7 @@ function getCachedData(dataCache, filePath) {
     path = require.resolve(path);
   }
 
-  var value = dataCache[path];
+  var value = dataCache.get(path);
   if (!value) {
     var input = fs.readFileSync(path, 'utf-8');
     var ast = parseToAst(input, path);
@@ -189,7 +189,7 @@ function getCachedData(dataCache, filePath) {
       },
       ast
     };
-    dataCache[path] = value;
+    dataCache.set(path, value);
   }
   return value;
 }