Improve the JSDoc comments #11235
Improve the JSDoc comments #11235
Conversation
|
/botio-linux preview |
|
/botio-linux preview |
|
Another thing I just noticed is that |
|
Yes, this is because the closure is called |
Given Lines 146 to 147 in 4af2755 Lines 1593 to 1596 in 4af2755 |
Sometimes we also used `Number` and `integer`, but `number` is what the JSDoc documentation recommends.
Sometimes we also used `String`, but `string` is the what the JSDoc documentation recommends.
…ments Square brackets are recommended to indicate optional parameters. Using them helps for automatically generating correct documentation.
Sometimes we also used `@return` or `@returns`, but `@type` is what the JSDoc documentation recommends. This also improves the documentation because before this commit the types were not shown and now they are.
Sometimes we also used `@return`, but `@returns` is what the JSDoc documentation recommends. Even though `@return` works as an alias, it's good to use the recommended syntax and to be consistent within the project.
timvandermeij
force-pushed
the
jsdoc
branch
2 times, most recently
from
243bf5d to
5ee5caa
Compare
|
/botio-linux preview |
From: Bot.io (Linux m4)ReceivedCommand cmd_preview from @timvandermeij received. Current queue size: 0 Live output at: http://54.67.70.0:8877/15dd7d913e2aab9/output.txt |
From: Bot.io (Linux m4)SuccessFull output at http://54.67.70.0:8877/15dd7d913e2aab9/output.txt Total script time: 1.63 mins Published |
…rker` Both classes live inside a closure with the same name, which confuses JSDoc. Move the documentation to the inner class to deduplicate them.
This file only contains helper functions and should not be listed in the documentation since they are not part of the public API.
This commit allows JSDoc to generate all API documentation in the `pdfjsLib` module (namespace) so the documentation becomes easier to navigate.
This commit series makes our JSDoc comments more consistent and allows us to generate better API documentation and TypeScript definition files.
I have been watching the discussions about both for some time now and figured we should get started with making improvements because I think it would be ideal from a maintenance perspective if we could generate them both instead of maintaining them manually. Therefore, I collected improvements both from the various discussions and the JSDoc documentation so the resulting output becomes more precise.
Note that this is groundwork for more documentation improvements, so more work definitely needs to be done. Thanks to the various people that discussed this and did proposals for this.
Before:
https://mozilla.github.io/pdf.js/api/draft/PDFDocumentProxy.html
After:
http://54.67.70.0:8877/15dd7d913e2aab9/api/draft/module-pdfjsLib-PDFDocumentProxy.html
(notice that all getters now have types and descriptions)