enforce JSDoc blocks above all functions

[ndhoule]

ESLint has JSDoc validation, but only if you don't have a newline between the JSDoc block and the function def.

Right now this is available via a plugin:

https://www.npmjs.com/package/eslint-plugin-require-jsdoc

[stephenmathieson]

-1 from me

this is a super common pattern and i think it's fine:

/**
 * Do some foo to `bar`.
 *
 * @param....
 */

function foo(bar) {
  return bar.map(baz)

  function baz(qux) {
    // ...
  }
}

i think a good code-review would point out missing documentation when necessary

[dominicbarnes]

fwiw, ESLint has native support for require-jsdoc

I usually turn it on as a warning, because missing docs won't break a page, but I want to be reminded that I've not gotten it done.

[ndhoule]

i think a good code-review would point out missing documentation when necessary

Sure, but:

1. Not all code reviews are good (people miss things)
2. Not every PR gets a review
3. Developers should have a mechanism for reminding them they should do things before review time so they don't feel as though an uncommunicated requirement was dumped on them after they've "finished" something. (Being on the reviewer end of this frustration is what prompted me to create eslint-config in the first place)
4. If the expectation at Segment is that all functions should be documented, it's a waste of my time as a reviewer to remind someone to document their functions. Computers are good at this

Not sure if you're saying that not every function needs a comment block, but I'm open to that idea if you are.

[stephenmathieson]

1. fair
2. this is result of a bad/missing review culture. let's fix that problem instead
3. we know to write dox, we just don't because nobody has cared until now
4. fair-ish

Computers are good at this

if eslint wouldn't make us change our coding style and knew whether or not a function/program was "mission critical", i'd agree with this statement

Not sure if you're saying that not every function needs a comment block, but I'm open to that idea if you are.

i'd say every top-scope function needs (probably) a comment block, but most others don't.. because of that, i don't think it's a good idea to turn this rule on