Improve wp.Backbone docs

[ericlewis]

Let's convert the docblocks to JSDoc.

[ocean90]

+1. 35465.diff​ is a good start.

[gma992]

Converted some more docblocks and added selector and views params

[DrewAPicture]

Assigning ownership to mark the good-first-bug as "claimed".

[adamsilverstein]

35465.2.diff​ refresh against trunk

[adamsilverstein]

35465.3.diff​:

• whitspace fixes (spaces for multiline indent)
• add explanation of options parameter
• still needs more work, some sections are missing docs

[atimmer]

Patch with all docblocks present

[atimmer]

Patch with all @since tags.

[atimmer]

In 42993:

Docs: Improve JSDoc for wp-includes/js/wp-backbone.js.

Props ericlewis, gma992, adamsilverstein.
Fixes #35465.

[birgire]

35465.6.diff​ is a suggestion that:

• Aligns related descriptions.
• Adds full stops to some summaries.
• Capitalizes object in * @param {array|object}
• Changes a two line // comment into a multiline comment using /*...*/.
• Changes $returns to $return.

Notes:

• I noticed further {?Object} and {?number}​here. Should we remove the question marks?

• Are the > and – really needed ​here?

[adamsilverstein]

I noticed further {?Object} and {?number}here. Should we remove the question marks?

The question mark indicates the field is optional. If the Object is optional it can stay. I don't see a number parameter in that function al all though, seems like that line can be removed?

Are the > and – really needed here?

These do seem out of place. I think you can leave out the '>' items or change them both to a regular '-' dash.

[birgire]

Replying to adamsilverstein:

The question mark indicates the field is optional. If the Object is optional it can stay.

Thanks @adamsilverstein, I skimmed through:

​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

when I noticed ?Object and ?number, but I didn't find a reference to it there.

I think it could be helpful to mention it in the Handbook.

I don't see a number parameter in that function al all though, seems like that line can be removed?

I wasn't exactly sure regarding that, so I didn't change that.

35465.7.diff​

• Removes > from description.
• Replaces – with - in description.
• Moves a word up to the line above, in description, for better readability.
• Makes a single alignment.

[netweb]

I've created #43828 that adds a JSDoc ESLint script, it can be run by downloading and applying the patch and updating the dependencies by running npm install and npm run lint:jsdoc to run the script.

The configuration comes by way of previous existing Gutenberg work, references are linked in #43828

I'll get the handbook updated to document all this.

cc @adamsilverstein @atimmer @birgire

[birgire]

Replying to netweb:

I've created #43828 that adds a JSDoc ESLint script, it can be run by downloading and applying the patch and updating the dependencies by running npm install and npm run lint:jsdoc to run the script.

Great, I tested running npm install and npm run lint:jsdoc, with output for all files:

> WordPress@5.0.0 lint:jsdoc /www/sites/test.local/wp
> eslint . --config .eslintrc-jsdoc.js

...
/path/to/src/wp-includes/js/wp-backbone.js
   23:14  error  Use 'Array' instead of 'array'      valid-jsdoc
   38:15  error  Use 'Array' instead of 'array'      valid-jsdoc
   44:3   error  Missing JSDoc return description    valid-jsdoc
   54:15  error  Use 'Array' instead of 'array'      valid-jsdoc
   80:3   error  Missing JSDoc return type           valid-jsdoc
  111:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  177:3   error  Missing JSDoc return type           valid-jsdoc
  200:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  200:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  231:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  231:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  408:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  408:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  455:6   error  Use @return instead                 valid-jsdoc
  499:3   error  Missing JSDoc @return for function  valid-jsdoc
  519:6   error  Use @return instead                 valid-jsdoc
  544:6   error  Use @return instead                 valid-jsdoc
...

â 3213 problems (3213 errors, 0 warnings)
  1935 errors, 0 warnings potentially fixable with the `--fix` option.

ps: how would we run this on a specific .js file?

[netweb]

Replying to birgire:

ps: how would we run this on a specific .js file?

For the time being, this should work:

• ./node_modules/.bin/eslint --config .eslintrc-jsdoc.js src/wp-includes/js/wp-backbone.js

And, if you tack --fix onto the end it will automagically fix 13 of the 17 errors for you ✨

• ./node_modules/.bin/eslint --config .eslintrc-jsdoc.js src/wp-includes/js/wp-backbone.js --fix

[birgire]

Thank you @netweb 🎉

$ ./node_modules/.bin/eslint --config .eslintrc-jsdoc.js src/wp-includes/js/wp-backbone.js

/path/to/src/wp-includes/js/wp-backbone.js
   23:14  error  Use 'Array' instead of 'array'      valid-jsdoc
   38:15  error  Use 'Array' instead of 'array'      valid-jsdoc
   44:3   error  Missing JSDoc return description    valid-jsdoc
   54:15  error  Use 'Array' instead of 'array'      valid-jsdoc
   80:3   error  Missing JSDoc return type           valid-jsdoc
  111:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  177:3   error  Missing JSDoc return type           valid-jsdoc
  200:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  200:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  231:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  231:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  408:14  error  Use 'Array' instead of 'array'      valid-jsdoc
  408:20  error  Use 'Object' instead of 'object'    valid-jsdoc
  455:6   error  Use @return instead                 valid-jsdoc
  499:3   error  Missing JSDoc @return for function  valid-jsdoc
  519:6   error  Use @return instead                 valid-jsdoc
  544:6   error  Use @return instead                 valid-jsdoc

â 17 problems (17 errors, 0 warnings)
  13 errors, 0 warnings potentially fixable with the `--fix` option.

 $ ./node_modules/.bin/eslint --config .eslintrc-jsdoc.js src/wp-includes/js/wp-backbone.js --fix

/path/to/src/wp-includes/js/wp-backbone.js
   44:3  error  Missing JSDoc return description    valid-jsdoc
   80:3  error  Missing JSDoc return type           valid-jsdoc
  177:3  error  Missing JSDoc return type           valid-jsdoc
  499:3  error  Missing JSDoc @return for function  valid-jsdoc

â 4 problems (4 errors, 0 warnings)

[atimmer]

In 42996:

Docs: Improve JSDoc for wp-includes/js/wp-backbone.js.

Changes some additional docs after [42993].

Props birgire, adamsilverstein, netweb.
Fixes #35465.

[atimmer]

@birgire Thank you for your contribution!

The ?number argument refers to a property that can be set on the object. When you document it like I did there JSDoc can recognize that the argument is a property on the object.