Improve Full Web IDL Appendix
relu91 opened this issue · 6 comments
Currently, we have an appendix section that collects all our WebIDL definitions in a single code block. However, in today's call, we agreed that it is not that useful because it does not provide sufficient context to outside users. Actions that we can take to improve it:
- Add a short introduction
- Provide useful documentation/comments on top of functions/attributes/interfaces
Another thing that we can fix is the partial namespace repetitions that here might be packed in one single namespace.
Q: You mean WebEx WebIDL definitions, right?
That is an automated appendix, used by specs - no need for any more comments, it's for reference, like a code listing. The spec text is the one meant to provide context and explanation.
Q: You mean
WebExWebIDL definitions, right?
yes right, fixed 🤦🏻 .
That is an automated appendix, used by specs - no need for any more comments, it's for reference, like a code listing. The spec text is the one meant to provide context and explanation.
Yes, but I would say that a short introduction would help the user to understand the goal of the section. Furthermore, if it has some comments (like the ones that we wrote in the typescript definitions it could help a little more the reader.
Yes, but I would say that a short introduction would help the user to understand the goal of the section. Furthermore, if it has some comments (like the ones that we wrote in the typescript definitions it could help a little more the reader.
No other spec is commenting in that section. It's not needed, it's not for that. It's enough there is an appendix with the full Web IDL - that's its only and full purpose. No other text is needed there.
We can probably close this issue, right? Or do you see anything left to do for us?