docs: Configuration objects do not show inner properties

[stephenplusplus]

Copied from original issue: googleapis/nodejs-storage#75

@jmdobry
November 1, 2017 4:41 PM

The options are documented in the source code, but for some reason don't show up on cloud.google.com

[stephenplusplus]

November 1, 2017 4:44 PM

That seems to be the case for all methods on Bucket. I don't know the spec on this, but maybe marking options as optional is enough, and it would be implied that options.* is optional. In diff:

 * @param {object} [options] Configuration options.
- * @param {string|File} [options.destination] The place to save
+ * @param {string|File} options.destination The place to save

[stephenplusplus]

@jmdobry
November 1, 2017 5:16 PM

I don't think that's the problem. When you run npm run docs locally and it uses the docstrap template, these options all show up fine in the generated docs. But when we generate the docs using our custom template on cloud.google.com, the options are missing. It must be a problem with the template we use on cloud.google.com.

[stephenplusplus]

December 19, 2017 6:04 PM

Does another team need to take a look into why these aren't showing up?

[stephenplusplus]

This popped up in another issue: googleapis/nodejs-firestore#91

This issue affects all of our APIs. None of the nested properties of an object are documented. For any given method, the user can only see that an "options" object is required, but none of the properties that must be specified within it.

For example, see the Firestore constructor. You must use the examples to deduce the correct way to authenticate the client. This pattern repeats for all methods, and we usually don't show all possible configuration options in the example block, since that would be overwhelming.

@alexander-fenster @jmdobry - who can take a look at this?

[jmdobry]

It appears to be an issue with our documentation generator.

[stephenplusplus]

What can we do?

[jmdobry]

@hegemonic and I need to look at hegemonic/jsdoc-baseline and figure out why the nested properties on params aren't showing up.

[stephenplusplus]

Already reported, it looks like: hegemonic/jsdoc-baseline#185

[hegemonic]

I've made a note to look into this, but I probably won't have time until next week. @jmdobry, if you have time to investigate now, please feel free to take this issue.

[stephenplusplus]

ping @alexander-fenster this seems pretty important :)

[hegemonic]

FYI, hegemonic/jsdoc-baseline#185 is now fixed (thanks, @jmdobry!).

[jmdobry]

I've republished all the API ref docs for all the latest versions of our Node.js Cloud client libraries

[stephenplusplus]

It looks great!