refactor(iterateJsdoc): avoid building/passing in checkJsdoc when contexts is an object returned from returns

refactor(iterateJsdoc): throw if provided a bad iterator rule
testing(iterateJsdoc): add testing file, checking basic arguments
testing(require-param): add missing coverage (`augmentsExtendsReplacesDocs`)

Author: brettz9

src/iterateJsdoc.js

@@ -277,9 +277,13 @@ export {
  * @param {{meta: any, returns?: any}} opts
  */
 export default function iterateJsdoc (iterator, opts) {
-  if (!opts.meta || !opts.meta.type || !['problem', 'suggestion', 'layout'].includes(opts.meta.type)) {
+  const metaType = _.get(opts, 'meta.type');
+  if (!metaType || !['problem', 'suggestion', 'layout'].includes(metaType)) {
     throw new TypeError('Rule must include `meta.type` option (with value "problem", "suggestion", or "layout")');
   }
+  if (typeof iterator !== 'function' && (!opts || typeof opts.returns !== 'function')) {
+    throw new TypeError('The iterator argument must be a function or an object with a `returns` method.');
+  }
 
   return {
     /**
@@ -296,6 +300,14 @@ export default function iterateJsdoc (iterator, opts) {
 
       const settings = getSettings(context);
 
+      let contexts = opts.returns;
+      if (typeof opts.returns === 'function') {
+        contexts = opts.returns(context, sourceCode);
+      }
+
+      if (!Array.isArray(contexts) && contexts) {
+        return contexts;
+      }
       const checkJsdoc = (node) => {
         const jsdocNode = getJSDocComment(sourceCode, node);
 
@@ -364,27 +376,19 @@ export default function iterateJsdoc (iterator, opts) {
           utils
         });
       };
-
-      let contexts = opts.returns;
-      if (typeof opts.returns === 'function') {
-        contexts = opts.returns(context, sourceCode, checkJsdoc);
+      if (!contexts) {
+        return {
+          ArrowFunctionExpression: checkJsdoc,
+          FunctionDeclaration: checkJsdoc,
+          FunctionExpression: checkJsdoc
+        };
       }
 
-      if (Array.isArray(contexts)) {
-        return contexts.reduce((obj, prop) => {
-          obj[prop] = checkJsdoc;
+      return contexts.reduce((obj, prop) => {
+        obj[prop] = checkJsdoc;
 
-          return obj;
-        }, {});
-      } else if (contexts) {
-        return contexts;
-      }
-
-      return {
-        ArrowFunctionExpression: checkJsdoc,
-        FunctionDeclaration: checkJsdoc,
-        FunctionExpression: checkJsdoc
-      };
+        return obj;
+      }, {});
     },
     meta: opts.meta
   };

test/iterateJsdoc.js

@@ -0,0 +1,93 @@
+/* eslint-disable max-nested-callbacks */
+
+import {
+  expect
+} from 'chai';
+// eslint-disable-next-line import/no-named-default
+import {parseComment, default as iterateJsdoc} from '../src/iterateJsdoc';
+
+describe('iterateJsdoc', () => {
+  describe('constructor', () => {
+    context('options', () => {
+      it('throws with missing options', () => {
+        expect(() => {
+          iterateJsdoc(() => {});
+        }).to.throw(TypeError);
+      });
+    });
+    context('meta', () => {
+      context('Invalid arguments', () => {
+        context('Invalid iterator', () => {
+          it('throws with missing function', () => {
+            expect(() => {
+              iterateJsdoc(undefined, {meta: {type: 'suggestion'}});
+            }).to.throw(TypeError);
+          });
+          it('throws with object missing `returns` method', () => {
+            expect(() => {
+              iterateJsdoc({}, {meta: {type: 'suggestion'}});
+            }).to.throw(TypeError);
+          });
+        });
+        context('Invalid options', () => {
+          it('throws with missing meta', () => {
+            expect(() => {
+              iterateJsdoc(() => {}, {});
+            }).to.throw(TypeError);
+          });
+          it('throws with empty meta', () => {
+            expect(() => {
+              iterateJsdoc(() => {}, {meta: {}});
+            }).to.throw(TypeError);
+          });
+          it('throws with bad type', () => {
+            expect(() => {
+              iterateJsdoc(() => {}, {meta: {type: 'bad'}});
+            }).to.throw(TypeError);
+          });
+        });
+      });
+      context('Valid arguments', () => {
+        it('Does not throw with function and options', () => {
+          expect(() => {
+            iterateJsdoc(() => {}, {meta: {type: 'suggestion'}});
+          }).to.not.throw();
+        });
+        it('Does not throw with object and options', () => {
+          expect(() => {
+            iterateJsdoc(undefined, {
+              meta: {type: 'suggestion'},
+              returns () {
+                return {};
+              }
+            });
+          }).to.not.throw();
+        });
+      });
+    });
+  });
+  describe('parseComment', () => {
+    context('Parses comments', () => {
+      it('', () => {
+        expect(parseComment({value: `* SomeDescription
+          @param {MyType} name desc
+        `}, '')).to.deep.equal({
+          description: 'SomeDescription',
+          line: 0,
+          source: 'SomeDescription\n@param {MyType} name desc',
+          tags: [
+            {
+              description: 'desc',
+              line: 1,
+              name: 'name',
+              optional: false,
+              source: '@param {MyType} name desc',
+              tag: 'param',
+              type: 'MyType'
+            }
+          ]
+        });
+      });
+    });
+  });
+});

test/rules/assertions/requireParam.js

@@ -405,6 +405,36 @@ export default {
           }
       `
     },
+    {
+      code: `
+          /**
+           * @augments
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          augmentsExtendsReplacesDocs: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @extends
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          augmentsExtendsReplacesDocs: true
+        }
+      }
+    },
     {
       code: `
           /**
@@ -545,6 +575,46 @@ export default {
           }
       `
     },
+    {
+      code: `
+          /**
+           * @augments
+           */
+          class A {
+            /**
+             *
+             */
+            quux (foo) {
+
+            }
+          }
+      `,
+      settings: {
+        jsdoc: {
+          augmentsExtendsReplacesDocs: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @extends
+           */
+          class A {
+            /**
+             *
+             */
+            quux (foo) {
+
+            }
+          }
+      `,
+      settings: {
+        jsdoc: {
+          augmentsExtendsReplacesDocs: true
+        }
+      }
+    },
     {
       code: `
           /**