The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.We've standardized on JSDoc, and many documentation issues were omitted in order to get the initial patch in. This issue will be used to track progress on fixing our JS documentation.
Process is simple:
- take one core module, create a new issue (set this issue as parent so we can track progress). Use this template:
- Title:
JSDoc <module>(replace with module name) - Category:
Task - Component:
documentation - Tags:
JavaScript, Novice - Parent issue:
2501679
- Title:
- Refer to JavaScript API documentation and comment standards to know our standards
- Fix that module documentation!
Overall comments on what to pay attention to:
- Check the 80 char limit for comments, and any reformatting problems (a single word on a line in the middle of a paragraph for example),
- Make a one line summary for function and variables that don't have one,
- If a docblock comment refers to another javascript method/function/variable/object use
{@link …}so that JSDoc can link to it, - Add documentation to every single parameter and return (aka. fix all ESLint jsdoc warning: #2494177: Enable ESLint warning for missing JSDoc).
Comments
Comment #1
nod_Comment #2
nod_Comment #3
jhodgdonAnother possible thing to do in this effort:
Add @link to appropriate places [TBD: what is "appropriate"?]
The API module will automatically make mentions of classes and functions and stuff in documentation into links, but JSDoc doesn't do that. So you have to manually put in @link tags. At least, I think so... It seems like that would be good to do as much as possible in the documentation for JS as well. Right?
Comment #4
nod_yup, adding it to the meta.
And thanks for the last JSDoc commit!
Comment #5
jhodgdonGreat! I was just going to suggest adding the Novice tag, but I see that is already there.
I've found with these types of big meta issues in the past that if the coordinator creates individual sub-issues and marks them Novice, they're more likely to get picked up and completed than if you just create the meta-issue and expect the novice contributors to add child issues. You can create a couple of them and see how they go, which may bring up more items to add to the issue summary here.
Alternatively, you can make very detailed instructions on how to set up the new issues -- keep in mind that Novice contributors will probably not be experienced at creating issues either.
Also, it helps if there is a list in the summary of the Meta of which issues still need to be filed, although it's a BIG pain to maintain that list.
Just a few thoughts, having been through this quite a few times before...
Comment #6
nod_Very good points, I'll get that set up this week then. Thanks!
Comment #7
nod_Comment #8
webchickSaving again to see where we're at, but we might be done here.
Comment #9
webchickNope. Looks like remaining issues are:
Close though! :D
Comment #10
webchickIncidentally, how/where does one go to view these docs?
Comment #11
nod_Doc can be read at http://read.theodoreb.net/drupal-jsapi/index.html just updated it.
See related issue for the actual plan to get that on d.o.
Comment #12
droplet commentedBoolean in Javascript should be `Boolean` (or case-insensitive `boolean` in JSDoc is also acceptable).
It's different than PHP. PHP accepts both `bool` or `boolean`. e.g.:
But only `Boolean` in JS
To match PHP Doc better, we should use small caps `boolean` to suppress 3rd parties validation warnings.
Comment #13
nod_Makes sense. +1
Comment #14
nod_Last two patches got in today! No more eslint error from documentation. Next step is to get this on api.d.o and get people reading :)
I've updated http://read.theodoreb.net/drupal-jsapi/ to track 8.1.x code since all eslint errors have been fixed for that one.
Comment #15
jhodgdonWoot!
Comment #16
andypostSo this can be closed
Comment #18
chrisfromredfinLooking through Novice issues for Design 4 Drupal 2016 - looks like this is safe to close?