JS Guide: Add section on JSDoc usage

[gerardo-rodriguez]

An example:

• how to properly document destructured parameters (see JSDocs "Documenting a destructuring parameter")

[Josh68]

From a discussion we had today, e.g. if passing in or returning an anonymous object to be destructured, you might do

@param {object} params
@param {object} params.foo - A foo object
@param {string} params.bar - The value of bar

or

@param {object} returnObjecct
@param {object} returnObject.foo - A foo object
@param {string} returnObject.bar - The value of bar

TBD, but wanted to put down what we discussed.

[gerardo-rodriguez]

I'd also like to land on a guideline of how long the comment lines should be to figure out when to wrap them.

Without doing research, I'd land on 80 characters max per line. But I'm open to other suggestions. 🙂

• https://softwareengineering.stackexchange.com/questions/351549/style-line-length-and-wrapping-of-comments-in-javascript

[Paul-Hebert]

I'd like to standardize around that as well. I've been manually doing line breaks where it "feels right" to prevent super long comments, but it would be nice to standardize, lint, and automate this process.

80 seems reasonable — maybe a little long from a typographical perspective where 80 is towards the upper bound of line lengths, but it sounds like a lot of tooling is already built around 80 and I don't think it would impact readability much compared to 60, or 70.

[Josh68]

Resurrecting a previous comment here, we had started to do something like this:

@param {Object} params
@param {Object} params.foo - A foo object
@param {string} params.bar - The value of bar

or

@param {Object} returnObjecct
@param {Object} returnObject.foo - A foo object
@param {string} returnObject.bar - The value of bar

Note that primitives are lowercased, otherwise param type is cap-cased. But https://stackoverflow.com/questions/32846527/do-primitive-type-names-need-to-be-uppercase-or-lowercase.

Food for thought.

[Paul-Hebert]

@tylersticka , I saw you mention an 80 char limit for comments in a PR comment. Should we officially standardize on that? Also, is there a good way to get that to show in VS Code you're aware of?

[calebeby]

ESLint lets you specify a different max-len for comments: https://eslint.org/docs/rules/max-len#options

[spaceninja]

is there a good way to get that to show in VS Code you're aware of?

Under Settings, search for "Rulers". Here's my setting:

  "editor.rulers": [80, 100, 120],

[Paul-Hebert]

Oh, sweet. Thanks guys!