Warn on missing JSDoc comment

[ndhoule]

We should be prepared to fix a lot of stuff when we merge this. JSDoc comments are only valid if they are immediately above the function body (no newline between them), so we're going to need to eliminate the newline everywhere.

[ndhoule]

cc @dominicbarnes

[dominicbarnes]

+1 (glad you chose the warning here too)

[stephenmathieson]

does this require comments on private functions too?

/**
 * Do the stuff with the things.
 * 
 * @param {Array} things
 * @return {Whatever}
 */

function stuff(things) {
  return whatever(things, 42)

  // requiring jsdoc here seems unnecessary imo
  function whatever(a, b) {
    // ...
  }
}

[dominicbarnes]

@stephenmathieson if I'm not mistaken, then yes. I don't know if there's a config to turn that off for "nested" functions, since using closures is a common pattern for getting privacy in non-CommonJS envs.

[yields]

Just curios, since newline between the function and the comment seems to be our "style", why not add a new rule instead of adhering to a rule that goes against our own style?

[stephenmathieson]

@yields that makes much more sense imo

[dominicbarnes]

This is a known/intentional limitation within ESLint I'm afraid, see eslint/eslint#2108. Basically, the extra line-break makes it ambiguous as JSDoc comments may apply to a file instead of a function.