From 7a548eb444123fe69743f43eb1f6545dd95d166e Mon Sep 17 00:00:00 2001 From: Michel Simonot Date: Wed, 4 Oct 2017 15:34:39 -0400 Subject: [PATCH] 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. --- __tests__/__snapshots__/bin.js.snap | 127 +++++++++++++++++++++++-- __tests__/__snapshots__/test.js.snap | 127 +++++++++++++++++++++++-- __tests__/fixture/html/nested.input.js | 9 ++ src/default_theme/index._ | 3 +- src/default_theme/index.js | 17 ++-- src/default_theme/paramProperty._ | 15 +++ src/default_theme/section._ | 17 ++-- src/default_theme/section_list._ | 3 +- 8 files changed, 284 insertions(+), 34 deletions(-) create mode 100644 src/default_theme/paramProperty._ diff --git a/__tests__/__snapshots__/bin.js.snap b/__tests__/__snapshots__/bin.js.snap index 28d01d242..82bb12bae 100644 --- a/__tests__/__snapshots__/bin.js.snap +++ b/__tests__/__snapshots__/bin.js.snap @@ -97,6 +97,12 @@ exports[`--config 1`] = ` #withOptions +
  • + #withDeepOptions +
    • + @@ -773,16 +779,20 @@ k.isArrayOfBuffers(); - options.foo string - - - + options.foo string + + + + + - options.bar number - - - + options.bar number + + + + + @@ -813,6 +823,107 @@ k.isArrayOfBuffers(); + + + + + +
    +
    +
    + ▸ + withDeepOptions(options) +
    +
    +
    +
    + + + +

    A function with a deep options parameter

    + + +
    withDeepOptions(options: Object)
    + + + + + + + + + + + +
    Parameters
    +
    + +
    +
    + options (Object) + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDescription
    options.foo string +
    options.bar Object +
    options.bar.buz string +
    + +
    + +
    + + + + + + + + + + + + + + +
    diff --git a/__tests__/__snapshots__/test.js.snap b/__tests__/__snapshots__/test.js.snap index 995315509..3b6fa1ffd 100644 --- a/__tests__/__snapshots__/test.js.snap +++ b/__tests__/__snapshots__/test.js.snap @@ -890,6 +890,12 @@ exports[`html nested.input.js 1`] = ` #withOptions +
  • + #withDeepOptions +
    • + @@ -1538,16 +1544,20 @@ k.isArrayOfBuffers(); - options.foo string - - - + options.foo string + + + + + - options.bar number - - - + options.bar number + + + + + @@ -1578,6 +1588,107 @@ k.isArrayOfBuffers(); + + +
    + + +
    +
    +
    + ▸ + withDeepOptions(options) +
    +
    +
    +
    + + + +

    A function with a deep options parameter

    + + +
    withDeepOptions(options: Object)
    + + + + + + + + + + + +
    Parameters
    +
    + +
    +
    + options (Object) + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDescription
    options.foo string +
    options.bar Object +
    options.bar.buz string +
    + +
    + +
    + + + + + + + + + + + + + + +
    diff --git a/__tests__/fixture/html/nested.input.js b/__tests__/fixture/html/nested.input.js index 47c443f52..5af9ef186 100644 --- 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._ index 24f3a3caf..859c8b78c 100644 --- 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 { %>
    <%=renderNote({ note: s })%>
    diff --git a/src/default_theme/index.js b/src/default_theme/index.js index 1cae8fdf7..eb7230fdc 100644 --- a/src/default_theme/index.js +++ b/src/default_theme/index.js @@ -22,12 +22,13 @@ module.exports = function( comments: Array, 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._ new file mode 100644 index 000000000..5291b2be3 --- /dev/null +++ b/src/default_theme/paramProperty._ @@ -0,0 +1,15 @@ + + <%- property.name %> <%= formatType(property.type) %> + <% if (property.default) { %> + (default <%- property.default %>) + <% } %> + <%= md(property.description, true) %> + +<% if(property.properties && property.properties.length) { %> + <% property.properties.forEach(function(childProperty) { %> + <%= renderParamProperty({ + property: childProperty, + renderParamProperty: renderParamProperty + }) %> + <% }) %> +<% } %> diff --git a/src/default_theme/section._ b/src/default_theme/section._ index 8228331c7..77adc0016 100644 --- a/src/default_theme/section._ +++ b/src/default_theme/section._ @@ -66,13 +66,10 @@ <% param.properties.forEach(function(property) { %> - - <%- property.name %> <%= formatType(property.type) %> - <% if (property.default) { %> - (default <%- property.default %>) - <% } %> - <%= md(property.description, true) %> - + <%= renderParamProperty({ + property: property, + renderParamProperty: renderParamProperty + }) %> <% }) %> @@ -137,16 +134,16 @@ <% if (section.members.static && section.members.static.length) { %>
    Static Members
    - <%= renderSectionList({ members: section.members.static, renderSection: renderSection, noun: 'Static Member' }) %> + <%= renderSectionList({ members: section.members.static, renderSection: renderSection, renderParamProperty: renderParamProperty, noun: 'Static Member' }) %> <% } %> <% if (section.members.instance && section.members.instance.length) { %>
    Instance Members
    - <%= renderSectionList({ members: section.members.instance, renderSection: renderSection, noun: 'Instance Member' }) %> + <%= renderSectionList({ members: section.members.instance, renderSection: renderSection, renderParamProperty: renderParamProperty, noun: 'Instance Member' }) %> <% } %> <% if (section.members.events && section.members.events.length) { %>
    Events
    - <%= renderSectionList({ members: section.members.events, renderSection: renderSection, noun: 'Event' }) %> + <%= renderSectionList({ members: section.members.events, renderSection: renderSection, renderParamProperty: renderParamProperty, noun: 'Event' }) %> <% } %> diff --git a/src/default_theme/section_list._ b/src/default_theme/section_list._ index 7063465fe..60d80ac32 100644 --- a/src/default_theme/section_list._ +++ b/src/default_theme/section_list._ @@ -11,7 +11,8 @@ <%= renderSection({ section: member, renderSection: renderSection, - nested: true + renderParamProperty: renderParamProperty, + nested: true }) %>