Merge branch 'master' into add-more-type-checks-to-valid-types

* master: (46 commits)
  feat(require-description-complete-sentence): limit checking to certain default tags likely to have descriptions or by `tags` array for additional choices; fixes gajus#337
  docs(newline-after-description): indicate applies on doc block
  docs(match-description): add alias `desc` to separate column
  docs(match-description): indicate application by default to `description`/`desc` and allowance for `property`/`prop`; clarify
  fix(match-description): ensure `prop` and `property` matching excludes name
  testing(require-param): fix test source (part of gajus#332)
  testing(require-param): fix test expectation (part of gajus#332)
  docs: generate docs
  chore: update devDeps (eslint-config-canonical, gitdown)
  fix(no-undefined-types): ensure working in all contexts; fixes gajus#324
  refactor(iterateJsdoc): reduce retrieval calls
  docs(check-examples): allow for whitespace at end
  feat(check-examples): add `paddedIndent` option
  fix(check-examples): preserve whitespace so as to report issues with whitespace-related rules such as `indent` (fixes gajus#211)
  chore(travis): fix Travis to use older unicorn version that supports Node 6 (and the canonical config that requires the earlier unicorn version)
  docs(require-returns, require-returns-check): indicate that these will report if multiple `returns` tags are present
  refactor: use `String.prototype.repeat` over lodash `repeat`
  refactor: apply (jsdoc-related) eslint rule fixes
  chore: add `lint-fix` script
  fix(newline-after-description): avoid matching duplicate or partial matches within tag descriptions after the block description; fixes gajus#328
  ...

.README/rules/check-examples.md

@@ -26,7 +26,7 @@ syntax highlighting). The following options determine whether a given
   so you may wish to use `(?:...)` groups where you do not wish the
   first such group treated as one to include. If no parenthetical group
   exists or matches, the whole matching expression will be used.
-  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```$"````
+  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```\s*$"````
   to only match explicitly fenced JavaScript blocks.
 * `rejectExampleCodeRegex` - Regex blacklist which rejects
   non-lintable examples (has priority over `exampleCodeRegex`). An example
@@ -37,6 +37,24 @@ If neither is in use, all examples will be matched. Note also that even if
 `captionRequired` is not set, any initial `<caption>` will be stripped out
 before doing the regex matching.
 
+#### `paddedIndent`
+
+This integer property allows one to add a fixed amount of whitespace at the
+beginning of the second or later lines of the example to be stripped so as
+to avoid linting issues with the decorative whitespace. For example, if set
+to a value of `4`, the initial whitespace below will not trigger `indent`
+rule errors as the extra 4 spaces on each subsequent line will be stripped
+out before evaluation.
+
+```js
+/**
+ * @example
+ *     anArray.filter((a) => {
+ *      return a.b;
+ *     });
+ */
+```
+
 #### `reportUnusedDisableDirectives`
 
 If not set to `false`, `reportUnusedDisableDirectives` will report disabled
@@ -98,7 +116,7 @@ decreasing precedence:
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `ClassDeclaration`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|everywhere|
 |Tags|`example`|
 |Options| *See above* |
 

.README/rules/match-description.md

@@ -8,6 +8,9 @@ by our supported Node versions):
 
 ``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]$``
 
+Applies to the jsdoc block description and `@description` (or `@desc`)
+by default but the `tags` option (see below) may be used to match other tags.
+
 #### Options
 
 ##### `matchDescription`
@@ -50,8 +53,10 @@ tag should be linted with the `matchDescription` value (or the default).
 }
 ```
 
-The tags `@param`/`@arg`/`@argument` will be properly parsed to ensure that
-the matched "description" text includes only the text after the name.
+The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
+parsed to ensure that the matched "description" text includes only the text
+after the name.
+
 All other tags will treat the text following the tag name, a space, and
 an optional curly-bracketed type expression (and another space) as part of
 its "description" (e.g., for `@returns {someType} some description`, the
@@ -88,8 +93,9 @@ Overrides the default contexts (see below).
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|N/A by default but see `tags` options|
+|Tags|docblock and `@description` by default but more with `tags`|
+|Aliases|`@desc`|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'description', 'desc', and any added to `tags` option, e.g., 'returns', 'return'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (accepts tags with names and optional type such as 'param', 'arg', 'argument', 'property', and 'prop', and accepts arbitrary list of other tags with an optional type (but without names), e.g., 'returns', 'return'), `mainDescription`, `matchDescription`|
 
 <!-- assertions matchDescription -->

.README/rules/newline-after-description.md

@@ -10,6 +10,6 @@ This rule allows one optional string argument. If it is `"always"` then a proble
 |---|---|
 |Context|everywhere|
 |Options|(a string matching `"always"|"never"`)|
-|Tags|N/A|
+|Tags|N/A (doc block)|
 
 <!-- assertions newlineAfterDescription -->

.README/rules/require-description-complete-sentence.md

@@ -9,10 +9,33 @@ tag descriptions are written in complete sentences, i.e.,
 * Every line in a paragraph (except the first) which starts with an uppercase
   character must be preceded by a line ending with a period.
 
+#### Options
+
+##### `tags`
+
+If you want additional tags to be checked for their descriptions, you may
+add them within this option.
+
+```js
+{
+  'jsdoc/require-description-complete-sentence': ['error', {tags: ['see', 'copyright']}]
+}
+```
+
+The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
+parsed to ensure that the checked "description" text includes only the text
+after the name.
+
+All other tags will treat the text following the tag name, a space, and
+an optional curly-bracketed type expression (and another space) as part of
+its "description" (e.g., for `@returns {someType} some description`, the
+description is `some description` while for `@some-tag xyz`, the description
+is `xyz`).
+
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param`, `returns`, `description`|
-|Aliases|`arg`, `argument`, `return`, `desc`|
-
+|Tags|doc block, `param`, `returns`, `description`, `property`, `summary`, `file`, `classdesc`, `todo`, `deprecated`, `throws`, 'yields' and others added by `tags`|
+|Aliases|`arg`, `argument`, `return`, `desc`, `prop`, `fileoverview`, `overview`, `exception`, `yield`|
+|Options|`tags`|
 <!-- assertions requireDescriptionCompleteSentence -->

.README/rules/require-example.md

@@ -7,20 +7,30 @@ Requires that all functions have examples.
 
 #### Options
 
-This rule has an object option:
+This rule has an object option.
 
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-  block avoids the need for an `@example`. Defaults to an empty array.
+##### `exemptedBy`
 
-- `avoidExampleOnConstructors` (default: false) - Set to `true` to avoid the
-  need for an example on a constructor (whether indicated as such by a
-  jsdoc tag or by being within an ES6 `class`).
+Array of tags (e.g., `['type']`) whose presence on the document
+block avoids the need for an `@example`. Defaults to an empty array.
+
+##### `avoidExampleOnConstructors`
+
+Set to `true` to avoid the need for an example on a constructor (whether
+indicated as such by a jsdoc tag or by being within an ES6 `class`).
+Defaults to `false`.
+
+##### `contexts`
+
+Set this to an array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+Overrides the default contexts (see below).
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`example`|
-|Options|`exemptedBy`, `avoidExampleOnConstructors`|
+|Options|`exemptedBy`, `avoidExampleOnConstructors`, `contexts`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireExample -->

.README/rules/require-returns-check.md

@@ -2,6 +2,8 @@
 
 Checks if the return expression exists in function body and in the comment.
 
+Will also report if multiple `@returns` tags are present.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|

.README/rules/require-returns.md

@@ -2,6 +2,8 @@
 
 Requires returns are documented.
 
+Will also report if multiple `@returns` tags are present.
+
 #### Options
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document

.travis.yml

@@ -7,7 +7,8 @@ node_js:
 before_install:
   - npm config set depth 0
 before_script:
-  - 'if [ -n "${ESLINT-}" ]; then npm install --no-save "eslint@${ESLINT}" ; fi'
+  - 'if [ "${ESLINT-}" == "6" ]; then npm install --no-save "eslint@${ESLINT}" ; fi'
+  - 'if [ "${ESLINT-}" == "5" ]; then npm install --no-save "eslint@${ESLINT}" eslint-config-canonical@17.1.2 eslint-plugin-unicorn@8.0.2 ; fi'
 notifications:
   email: false
 sudo: false