Need format for specifying event properties

[arthurevans]

It's not clear whether this is supported at present.

JSDoc uses something like this:

@event seed-element-lasers
@type {object} 
@property {string} sound - Sound emitted by lasers.
@property {boolean} useGreen - Green lasers are scarier.

[atotic]

This is what we know so far:
Events should be documented inside Polymer({}) javascript.

We declare an event like this
@event <event name>

Documenting detail parameter is murkier. Closure diverges from jsdoc standard here.
This is the recommended format from @jklein24:

    * @param {{externalChange:boolean}} detail -
    *     externalChange: true if change occured in different window.

This shows up weirdly inside iron-doc-viewer, 2nd line becomes a code block in markdown. And how do we deal with an additional parameter I do not know. It is an issue that spans 3 teams: @jklein24 , hydrolysis, and iron-doc-viewer.

Closure standard: https://developers.google.com/closure/compiler/docs/js-for-compiler
Closure is concerned with correctness, not pretty formatting

[garlicnation]

What if we don't try to parse markdown from @param or other type-specifying tags?

[atotic]

Problem is not markdown, there is no way to make these docs look good in Closure syntax. Closure's way of specifying params does not let you document sub-properties in a readable way. For example, if event.detail has two members, you specify it like this in Closure:

 * @param {{externalChange:boolean, storage:Object}} detail -
 * externalChange: true if change occured in different window.
 * storage: some other change doc

Your property.description becomes:

externalChange: true if change occured in different window. storage: some other change doc

which looks crappy when rendered. You could use some markdown hacks to make it look better, but this would require doc writer to know those markdown hacks. Without markdown, it is just one long line.

jsdoc standard solves this problem by allowing you to specify each subproperty separately like this:

@param {boolean} detail.externalChange - true if change occured in different window
@param {boolean} detail.storage - some other change doc

which would look great when rendered. But Closure does not allow this, there can be no '.' in property name.

We can either:

• have crappy looking docs for complex @params (maybe use markdown hacks to reduce crapiness)
• have Closure start supporting jsdoc standard, or at least ignore valid jsdoc @param tags that are invalid Closure.

[jklein24]

Unfortunately, I'd say the latter is extremely unlikely, but +cc @MatrixFrog just in case.

[MatrixFrog]

We used to ignore certain types of invalid @param annotations, including these. We changed that in google/closure-compiler@8fb5fce

I would recommend a typedef if the param type gets too long.

[atotic]

Then for complex parameters to look good, we'll have to handle @typedef in hydrolysis.

[garlicnation]

+1 to @typedef. I use it all the time in my pure JS code.

[rictic]

We have this in the schema of Analyzer 2.0 but I don't think we're parsing it out yet. Leaving this bug open.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.