From 497825329e85b4587595b6f68833c55569713107 Mon Sep 17 00:00:00 2001 From: perry Date: Tue, 12 Apr 2016 19:13:28 -0500 Subject: [PATCH] docs(dgeni): a better formatting fix for methods that return objects. Rel ionic-site#540 --- ionic/components/content/content.ts | 26 +++++----- scripts/docs/dgeni-config.js | 8 +-- .../docs/processors/parse-returns-object.js | 50 +++++++++++++++++++ scripts/docs/templates/common.template.html | 16 +++++- 4 files changed, 83 insertions(+), 17 deletions(-) create mode 100644 scripts/docs/processors/parse-returns-object.js diff --git a/ionic/components/content/content.ts b/ionic/components/content/content.ts index ae18c71a43..3c5cdf6579 100644 --- a/ionic/components/content/content.ts +++ b/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
- *       number dimensions.contentHeight content offsetHeight
- *       number dimensions.contentTop content offsetTop
- *       number dimensions.contentBottom content offsetTop+offsetHeight
- *       number dimensions.contentWidth content offsetWidth
- *       number dimensions.contentLeft content offsetLeft
- *       number dimensions.contentRight content offsetLeft + offsetWidth
- *       number dimensions.scrollHeight scroll scrollHeight
- *       number dimensions.scrollTop scroll scrollTop
- *       number dimensions.scrollBottom scroll scrollTop + scrollHeight
- *       number dimensions.scrollWidth scroll scrollWidth
- *       number dimensions.scrollLeft scroll scrollLeft
- *       number dimensions.scrollRight scroll scrollLeft + scrollWidth
+ * @returns {object} dimensions The content and scroll elements' dimensions + * {number} dimensions.contentHeight content offsetHeight + * {number} dimensions.contentTop content offsetTop + * {number} dimensions.contentBottom content offsetTop+offsetHeight + * {number} dimensions.contentWidth content offsetWidth + * {number} dimensions.contentLeft content offsetLeft + * {number} dimensions.contentRight content offsetLeft + offsetWidth + * {number} dimensions.scrollHeight scroll scrollHeight + * {number} dimensions.scrollTop scroll scrollTop + * {number} dimensions.scrollBottom scroll scrollTop + scrollHeight + * {number} dimensions.scrollWidth scroll scrollWidth + * {number} dimensions.scrollLeft scroll scrollLeft + * {number} dimensions.scrollRight scroll scrollLeft + scrollWidth */ getContentDimensions() { let _scrollEle = this._scrollEle; diff --git a/scripts/docs/dgeni-config.js b/scripts/docs/dgeni-config.js index 1fe650ff76..d63a1b0b57 100644 --- a/scripts/docs/dgeni-config.js +++ b/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(){ diff --git a/scripts/docs/processors/parse-returns-object.js b/scripts/docs/processors/parse-returns-object.js new file mode 100644 index 0000000000..4660d76b9f --- /dev/null +++ b/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+)/, '$1'); + 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; + } + } + }; +}; diff --git a/scripts/docs/templates/common.template.html b/scripts/docs/templates/common.template.html index 6dc9b12c5f..5a6675653f 100644 --- a/scripts/docs/templates/common.template.html +++ b/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 -@>
+ <@- for param in params -@> + <$ param.type $> <$ param.key $> <$ param.description $>
+ <@- endfor @> + <@- endif @> +<@- endmacro -@> + <@ macro githubViewLink(doc) -@> <$ doc.fileInfo.relativePath $> (line <$ doc.location.start.line+1 $>) <@- endmacro -@> @@ -241,6 +249,9 @@ Improve this doc
Returns: <$ typeInfo(method.returns) $> +<@ if method.returnsObjectParams @> +<$ returnObject(method.returnsObjectParams) $> +<@ endif @>
<@ endif @> <@ endif @> @@ -277,6 +288,9 @@ Improve this doc
Returns: <$ typeInfo(method.returns) $> +<@ if method.returnsObjectParams @> +<$ returnObject(method.returnsObjectParams) $> +<@ endif @>
<@ endif @>