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:

  1. 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
  2. Refer to JavaScript API documentation and comment standards to know our standards
  3. 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

nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes
nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Another 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?

nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes

yup, adding it to the meta.

And thanks for the last JSDoc commit!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Great! 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...

nod_’s picture

nod_
Primary language French
Location Lille
commented

Very good points, I'll get that set up this week then. Thanks!

nod_’s picture

nod_
Primary language French
Location Lille
commented
Title: [Meta] Document JavaScript » Document JavaScript
Category: Task » Plan
webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Issue summary: View changes

Saving again to see where we're at, but we might be done here.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Nope. Looks like remaining issues are:

Close though! :D

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Incidentally, how/where does one go to view these docs?

nod_’s picture

nod_
Primary language French
Location Lille
commented
Related issues: +#2501135: Add JSDoc site to api.drupal.org

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.

droplet’s picture

droplet commented

Boolean 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.:

var_dump((boolean) 1);
var_dump((bool) 1);

But only `Boolean` in JS

Boolean(1);
new Boolean;

To match PHP Doc better, we should use small caps `boolean` to suppress 3rd parties validation warnings.

nod_’s picture

nod_
Primary language French
Location Lille
commented

Makes sense. +1

nod_’s picture

nod_
Primary language French
Location Lille
commented

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.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Woot!

andypost’s picture

andypost
he/him
Primary language Russian
commented

So this can be closed

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

chrisfromredfin’s picture

chrisfromredfin
he/him/his
Primary language English
Location Portland, Maine
commented
Status: Active » Closed (fixed)

Looking through Novice issues for Design 4 Drupal 2016 - looks like this is safe to close?