-
Notifications
You must be signed in to change notification settings - Fork 200
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Need format for specifying event properties #1364
Comments
This is what we know so far: We declare an event like this Documenting detail parameter is murkier. Closure diverges from jsdoc standard here.
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 |
What if we don't try to parse markdown from |
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:
Your property.description becomes:
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:
which would look great when rendered. But Closure does not allow this, there can be no '.' in property name. We can either: |
Unfortunately, I'd say the latter is extremely unlikely, but +cc @MatrixFrog just in case. |
We used to ignore certain types of invalid I would recommend a typedef if the param type gets too long. |
Then for complex parameters to look good, we'll have to handle @typedef in hydrolysis. |
+1 to @typedef. I use it all the time in my pure JS code. |
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. |
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. |
It's not clear whether this is supported at present.
JSDoc uses something like this:
The text was updated successfully, but these errors were encountered: