docs(dgeni): a better formatting fix for methods that return objects. Rel ionic-site#540

ionic/components/content/content.ts

@@ -312,19 +312,19 @@ export class Content extends Ion {
 
   /**
    * Returns the content and scroll elements' dimensions.
-   * @returns {object} dimensions  The content and scroll elements' dimensions <br>
+   * @returns {object} dimensions  The content and scroll elements' dimensions
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentHeight  content offsetHeight <br>
+   * {number} dimensions.contentHeight  content offsetHeight
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentTop  content offsetTop <br>
+   * {number} dimensions.contentTop  content offsetTop
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentBottom  content offsetTop+offsetHeight <br>
+   * {number} dimensions.contentBottom  content offsetTop+offsetHeight
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentWidth  content offsetWidth <br>
+   * {number} dimensions.contentWidth  content offsetWidth
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentLeft  content offsetLeft <br>
+   * {number} dimensions.contentLeft  content offsetLeft
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.contentRight  content offsetLeft + offsetWidth <br>
+   * {number} dimensions.contentRight  content offsetLeft + offsetWidth
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollHeight  scroll scrollHeight <br>
+   * {number} dimensions.scrollHeight  scroll scrollHeight
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollTop  scroll scrollTop <br>
+   * {number} dimensions.scrollTop  scroll scrollTop
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollBottom  scroll scrollTop + scrollHeight <br>
+   * {number} dimensions.scrollBottom  scroll scrollTop + scrollHeight
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollWidth  scroll scrollWidth <br>
+   * {number} dimensions.scrollWidth  scroll scrollWidth
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollLeft  scroll scrollLeft <br>
+   * {number} dimensions.scrollLeft  scroll scrollLeft
-   * &nbsp; &nbsp; &nbsp; <code>number</code> dimensions.scrollRight  scroll scrollLeft + scrollWidth <br>
+   * {number} dimensions.scrollRight  scroll scrollLeft + scrollWidth
    */
   getContentDimensions() {
     let _scrollEle = this._scrollEle;

scripts/docs/dgeni-config.js

@@ -11,9 +11,11 @@ var _ = require('lodash');
 var config = require('../config.json');
 
 // Define the dgeni package for generating the docs
-module.exports = function(currentVersion){
+module.exports = function(currentVersion) {
 
-  return new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, gitPackage])
+  return new Package('ionic-v2-docs',
+                     [jsdocPackage, nunjucksPackage, typescriptPackage,
+                      linksPackage, gitPackage])
 
 .processor(require('./processors/latest-version'))
 .processor(require('./processors/index-page'))
@@ -21,7 +23,7 @@ module.exports = function(currentVersion){
 .processor(require('./processors/remove-private-members'))
 .processor(require('./processors/hide-private-api'))
 .processor(require('./processors/collect-inputs-outputs'))
-
+.processor(require('./processors/parse-returns-object'))
 
 // for debugging docs
 // .processor(function test(){

scripts/docs/processors/parse-returns-object.js

@@ -0,0 +1,50 @@
+module.exports = function removePrivateApi() {
+
+  /*
+   * This processor assumes the format:
+   * @returns {object} object general description
+   * {number} objectName.propertyName  property description
+   * {number} objectName.propertyName  objectName.propertyName
+   * ...
+   *
+  */
+  return {
+    name: 'parse-returns-object',
+    description: 'If a method returns an object, and the values are listed ' +
+                 'out, parse them in to anobject that can be iterated by dgeni',
+    $runBefore: ['rendering-docs'],
+    $process: function(docs) {
+      var publicDocs = [];
+      docs.forEach(function(doc, i) {
+        if (doc.members) {
+          docs[i].members.forEach(function(member, ii) {
+            if (member.returns && member.returns.typeExpression == 'object') {
+              var params = docs[i].members[ii].returns.description.split('\n{');
+              docs[i].members[ii].returns.description = params.shift();
+              if (params.length) {
+                docs[i].members[ii].returns.description = docs[i].members[ii]
+                  .returns.description
+                  .replace(/^(\w+)/, '<span class="fixed-width">$1</span>');
+                docs[i].members[ii].returnsObjectParams = parseReturn(params);
+              }
+            }
+          });
+        }
+      });
+      return docs;
+
+      function parseReturn(lineArray) {
+        var params = [];
+        lineArray.forEach(function(line, l) {
+          params.push({
+            type: line.substr(0, line.indexOf('} ')),
+            key: line.substr(line.indexOf('} ') + 2,
+                             line.indexOf('  ') - line.indexOf('} ') - 2),
+            description: line.substr(line.indexOf('  ') + 2)
+          });
+        });
+        return params;
+      }
+    }
+  };
+};

scripts/docs/templates/common.template.html

@@ -6,7 +6,7 @@ path: "<$ doc.path $>"
 category: api
 id: "<$ doc.name|lower|replace(' ','-') $>"
 title: "<@ if doc.docType == "directive" @><$ doc.name | dashCase $><@ else @><$ doc.name $><@ endif @>"
-header_sub_title: "<$ doc.docType | capital $> in module <$ doc.module $>"
+header_sub_title: "Ionic API Documentation"
 doc: "<$ doc.name $>"
 docType: "<$ doc.docType $>"
 <@ if doc.demo @>show_preview_device: true
@@ -23,6 +23,14 @@ angular_controller: APIDemoCtrl <@ endif @>
   <@- endif @>
 <@- endmacro -@>
 
+<@ macro returnObject(params) -@>
+  <@- if params -@><br>
+    <@- for param in params -@>
+      <code><$ param.type $></code> <span class="fixed-width"><$ param.key $></span> <$ param.description $><br>
+    <@- endfor @>
+  <@- endif @>
+<@- endmacro -@>
+
 <@ macro githubViewLink(doc) -@>
   <a href="https://github.com/<$ versionInfo.gitRepoInfo.owner $>/<$ versionInfo.gitRepoInfo.repo $>/tree/master/<$ doc.fileInfo.relativePath $>#L<$ doc.location.start.line+1 $>-L<$ doc.location.end.line+1 $>"><$ doc.fileInfo.relativePath $> (line <$ doc.location.start.line+1 $>)</a>
 <@- endmacro -@>
@@ -241,6 +249,9 @@ Improve this doc
 <div class="anchor" class="return-value">
 <i class="icon ion-arrow-return-left"></i>
 <b>Returns:</b> <$ typeInfo(method.returns) $>
+<@ if method.returnsObjectParams @>
+<$ returnObject(method.returnsObjectParams) $>
+<@ endif @>
 </div>
 <@ endif @>
 <@ endif @>
@@ -277,6 +288,9 @@ Improve this doc
 <div class="return-value">
 <i class="icon ion-arrow-return-left"></i>
 <b>Returns:</b> <$ typeInfo(method.returns) $>
+<@ if method.returnsObjectParams @>
+<$ returnObject(method.returnsObjectParams) $>
+<@ endif @>
 </div>
 <@ endif @>