fix(html): Display all levels of parameter properties. (#933)

Fix default_theme to render all parameter properties. - Split the parameter property template portion into its own partial. - Have the new partial recursively call itself if there are sub-properties.
documentationjs · Oct 4, 2017 · 7a548eb · 7a548eb
1 parent e203df5
commit 7a548eb
Show file tree

Hide file tree

Showing 8 changed files with 284 additions and 34 deletions.
diff --git a/__tests__/__snapshots__/bin.js.snap b/__tests__/__snapshots__/bin.js.snap
@@ -97,6 +97,12 @@ exports[`--config 1`] = `
                         #withOptions
                       </a></li>
                       
+                      <li><a
+                        href='#klasswithdeepoptions'
+                        class='regular pre-open'>
+                        #withDeepOptions
+                      </a></li>
+                      
                     </ul>
                   
                   
@@ -773,16 +779,20 @@ k.isArrayOfBuffers();</pre>
             <tbody class='mt1'>
               
                 <tr>
-                  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
-                  </td>
-                  <td class='break-word'><span></span></td>
-                </tr>
+  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
               
                 <tr>
-                  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number\\">number</a></code>
-                  </td>
-                  <td class='break-word'><span></span></td>
-                </tr>
+  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number\\">number</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
               
             </tbody>
           </table>
@@ -813,6 +823,107 @@ k.isArrayOfBuffers();</pre>
   
 
   
+</section>
+
+      </div>
+    </div>
+  
+    <div class='border-bottom' id='klasswithdeepoptions'>
+      <div class=\\"clearfix small pointer toggle-sibling\\">
+        <div class=\\"py1 contain\\">
+            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
+            <span class='code strong strong truncate'>withDeepOptions(options)</span>
+        </div>
+      </div>
+      <div class=\\"clearfix display-none toggle-target\\">
+        <section class='p2 mb2 clearfix bg-white minishadow'>
+
+  
+
+  <p>A function with a deep options parameter</p>
+
+
+  <div class='pre p1 fill-light mt0'>withDeepOptions(options: <a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a>)</div>
+  
+  
+
+  
+  
+  
+  
+  
+  
+
+  
+    <div class='py1 quiet mt1 prose-big'>Parameters</div>
+    <div class='prose'>
+      
+        <div class='space-bottom0'>
+          <div>
+            <span class='code bold'>options</span> <code class='quiet'>(<a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a>)</code>
+	    
+          </div>
+          
+          <table class='mt1 mb2 fixed-table h5 col-12'>
+            <colgroup>
+              <col width='30%' />
+              <col width='70%' />
+            </colgroup>
+            <thead>
+              <tr class='bold fill-light'>
+                <th>Name</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody class='mt1'>
+              
+                <tr>
+  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
+              
+                <tr>
+  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+  
+    <tr>
+  <td class='break-word'><span class='code bold'>options.bar.buz</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
+  
+
+
+              
+            </tbody>
+          </table>
+          
+        </div>
+      
+    </div>
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
 </section>
 
       </div>

diff --git a/__tests__/__snapshots__/test.js.snap b/__tests__/__snapshots__/test.js.snap
@@ -890,6 +890,12 @@ exports[`html nested.input.js 1`] = `
                         #withOptions
                       </a></li>
 
+                      <li><a
+                        href='#klasswithdeepoptions'
+                        class='regular pre-open'>
+                        #withDeepOptions
+                      </a></li>
+
                     </ul>
 
 
@@ -1538,16 +1544,20 @@ k.isArrayOfBuffers();</pre>
             <tbody class='mt1'>
 
                 <tr>
-                  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
-                  </td>
-                  <td class='break-word'><span></span></td>
-                </tr>
+  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
 
                 <tr>
-                  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number\\">number</a></code>
-                  </td>
-                  <td class='break-word'><span></span></td>
-                </tr>
+  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number\\">number</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
 
             </tbody>
           </table>
@@ -1578,6 +1588,107 @@ k.isArrayOfBuffers();</pre>
 
 
 
+</section>
+
+      </div>
+    </div>
+
+    <div class='border-bottom' id='klasswithdeepoptions'>
+      <div class=\\"clearfix small pointer toggle-sibling\\">
+        <div class=\\"py1 contain\\">
+            <a class='icon pin-right py1 dark-link caret-right'>▸</a>
+            <span class='code strong strong truncate'>withDeepOptions(options)</span>
+        </div>
+      </div>
+      <div class=\\"clearfix display-none toggle-target\\">
+        <section class='p2 mb2 clearfix bg-white minishadow'>
+
+
+
+  <p>A function with a deep options parameter</p>
+
+
+  <div class='pre p1 fill-light mt0'>withDeepOptions(options: <a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a>)</div>
+
+
+
+
+
+
+
+
+
+
+
+    <div class='py1 quiet mt1 prose-big'>Parameters</div>
+    <div class='prose'>
+
+        <div class='space-bottom0'>
+          <div>
+            <span class='code bold'>options</span> <code class='quiet'>(<a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a>)</code>
+
+          </div>
+
+          <table class='mt1 mb2 fixed-table h5 col-12'>
+            <colgroup>
+              <col width='30%' />
+              <col width='70%' />
+            </colgroup>
+            <thead>
+              <tr class='bold fill-light'>
+                <th>Name</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody class='mt1'>
+
+                <tr>
+  <td class='break-word'><span class='code bold'>options.foo</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
+
+                <tr>
+  <td class='break-word'><span class='code bold'>options.bar</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object\\">Object</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
+    <tr>
+  <td class='break-word'><span class='code bold'>options.bar.buz</span> <code class='quiet'><a href=\\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\\">string</a></code>
+  </td>
+  <td class='break-word'><span></span></td>
+</tr>
+
+
+
+
+
+
+            </tbody>
+          </table>
+
+        </div>
+
+    </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 </section>
 
       </div>

diff --git a/__tests__/fixture/html/nested.input.js b/__tests__/fixture/html/nested.input.js
@@ -26,6 +26,15 @@ Klass.prototype.getFoo = function() {
  */
 Klass.prototype.withOptions = function(options, otherOptions) {};
 
+/**
+ * A function with a deep options parameter
+ * @param {Object} options
+ * @param {string} options.foo
+ * @param {Object} options.bar
+ * @param {string} options.bar.buz
+ */
+Klass.prototype.withDeepOptions = function(options) {};
+
 /**
  * @typedef CustomError
  * @name CustomError

diff --git a/src/default_theme/index._ b/src/default_theme/index._
@@ -97,7 +97,8 @@
             <%= renderSection({
               section: s,
               renderSection: renderSection,
-              renderSectionList: renderSectionList
+              renderSectionList: renderSectionList,
+              renderParamProperty: renderParamProperty
             }) %>
           <% } else { %>
             <div class='keyline-top-not py2'><%=renderNote({ note: s })%></div>

diff --git a/src/default_theme/index.js b/src/default_theme/index.js
@@ -22,12 +22,13 @@ module.exports = function(
   comments: Array<Comment>,
   config: DocumentationConfig
 ) {
-  var linkerStack = new LinkerStack(
-    config
-  ).namespaceResolver(comments, function(namespace) {
-    var slugger = new GithubSlugger();
-    return '#' + slugger.slug(namespace);
-  });
+  var linkerStack = new LinkerStack(config).namespaceResolver(
+    comments,
+    function(namespace) {
+      var slugger = new GithubSlugger();
+      return '#' + slugger.slug(namespace);
+    }
+  );
 
   var formatters = createFormatters(linkerStack.link);
 
@@ -98,6 +99,10 @@ module.exports = function(
     fs.readFileSync(path.join(__dirname, 'note._'), 'utf8'),
     sharedImports
   );
+  sharedImports.imports.renderParamProperty = _.template(
+    fs.readFileSync(path.join(__dirname, 'paramProperty._'), 'utf8'),
+    sharedImports
+  );
 
   var pageTemplate = _.template(
     fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'),

diff --git a/src/default_theme/paramProperty._ b/src/default_theme/paramProperty._
@@ -0,0 +1,15 @@
+<tr>
+  <td class='break-word'><span class='code bold'><%- property.name %></span> <code class='quiet'><%= formatType(property.type) %></code>
+  <% if (property.default) { %>
+    (default <code><%- property.default %></code>)
+  <% } %></td>
+  <td class='break-word'><span><%= md(property.description, true) %></span></td>
+</tr>
+<% if(property.properties && property.properties.length) { %>
+  <% property.properties.forEach(function(childProperty) { %>
+    <%= renderParamProperty({
+      property: childProperty,
+      renderParamProperty: renderParamProperty
+    }) %>
+  <% }) %>
+<% } %>