Enable valid-jsdoc rule in linter.

[aljones15]

turns on these rules:

    'jsdoc/check-examples': 1,
    'jsdoc/check-param-names': 1,
    'jsdoc/check-tag-names': 1,
    'jsdoc/check-types': 1,
    'jsdoc/newline-after-description': 1,
    'jsdoc/no-undefined-types': 1,
    'jsdoc/require-description': 1,
    'jsdoc/require-description-complete-sentence': 1,
    'jsdoc/require-example': 1,
    'jsdoc/require-hyphen-before-param-description': 1,
    'jsdoc/require-param': 1,
    'jsdoc/require-param-description': 1,
    'jsdoc/require-param-name': 1,
    'jsdoc/require-param-type': 1,
    'jsdoc/require-returns': 1,
    'jsdoc/require-returns-check': 1,
    'jsdoc/require-returns-description': 1,
    'jsdoc/require-returns-type': 1,
    'jsdoc/valid-types': 1,

[mattcollier]

docs that you referenced indicate that this rule is deprecated: https://eslint.org/blog/2018/11/jsdoc-end-of-life

[aljones15]

wow... ok well let's add the plugin then

https://github.com/gajus/eslint-plugin-jsdoc

need to decide on rules for this.

@mattcollier I enabled all the rules going to test it out on the bedrock-web-account

this branch os crypto-ld is currently using this branch:

https://github.com/digitalbazaar/crypto-ld/tree/enhancement/jsdoc-to-readme

[mattcollier]

@aljones15 I used this some this week, and for projects that have jsdocs, I think it's fine.

However, we have use cases where we need nodejs linting without jsdocs, so I would like to somehow make the jsdoc stuff (and the requisite deps) optional. Our bedrock-foo-http modules for instance do not have public nodejs APIs. So for those, there might be some jsdocs for some private functions or something, but we won't be using the jsdoc2markdown stuff. In the fullness of time, we may want a RAML to markdown thing going on, but not now.

So, do we need to do an extension like with vue? So we use eslint-config-digitalbazaar/jsdocs when we want that enabled?

[aljones15]

hey one idea might be something like this:

module.exports = function() {
  const rules = {
    eslintRuleshere...
  }
  try {
    require('eslint-plugin-jsdoc');
    return rules;
  } catch(e) {
    throw new Error('This rule set requires js-doc to be installed');
  }
}

Hence we get something out of the .js file in addition to clearly warning the user that a dependency is needed.

[mattcollier]

@aljones15 I saw some conversation related having to specify @description vs implicit. I thought this may have already been patched but that's not the case. Will you apply that patch?

[aljones15]

@aljones15 I saw some conversation related having to specify @description vs implicit. I thought this may have already been patched but that's not the case. Will you apply that patch?

good catch here guess I forgot to change that to a 0. made the change should be in the repo in a second.