Merge pull request #221 from brettz9/avoidExampleOnConstructors

Avoid example on constructors

Author: brettz9

README.md

@@ -1823,6 +1823,23 @@ function quux () {
  */
 function quux () {
 
+}
+// Message: Missing JSDoc @example description.
+
+/**
+ * @constructor
+ */
+function quux () {
+
+}
+// Message: Missing JSDoc @example declaration.
+
+/**
+ * @constructor
+ * @example
+ */
+function quux () {
+
 }
 // Message: Missing JSDoc @example description.
 ````
@@ -1855,6 +1872,30 @@ function quux () {
  */
 function quux () {
 
+}
+
+/**
+ * @constructor
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}}
+
+/**
+ * @constructor
+ * @example
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}}
+
+/**
+ * @inheritdoc
+ */
+function quux () {
+
 }
 ````
 

src/iterateJsdoc.js

@@ -42,6 +42,7 @@ const curryUtils = (
   allowAugmentsExtendsWithoutParam,
   checkSeesForNamepaths,
   forceRequireReturn,
+  avoidExampleOnConstructors,
   ancestors,
   sourceCode,
   context
@@ -142,6 +143,11 @@ const curryUtils = (
   utils.isNamepathType = (tagName) => {
     return jsdocUtils.isNamepathType(tagName, checkSeesForNamepaths);
   };
+
+  utils.avoidExampleOnConstructors = () => {
+    return avoidExampleOnConstructors;
+  };
+
   utils.passesEmptyNamepathCheck = (tag) => {
     return !tag.name && allowEmptyNamepaths && _.includes([
       // These may serve some minor purpose when empty
@@ -243,6 +249,7 @@ export default (iterator, options) => {
       const allowAugmentsExtendsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
       const checkSeesForNamepaths = Boolean(_.get(context, 'settings.jsdoc.checkSeesForNamepaths'));
       const forceRequireReturn = Boolean(_.get(context, 'settings.jsdoc.forceRequireReturn'));
+      const avoidExampleOnConstructors = Boolean(_.get(context, 'settings.jsdoc.avoidExampleOnConstructors'));
 
       const checkJsdoc = (node) => {
         const jsdocNode = sourceCode.getJSDocComment(node);
@@ -311,6 +318,7 @@ export default (iterator, options) => {
           allowAugmentsExtendsWithoutParam,
           checkSeesForNamepaths,
           forceRequireReturn,
+          avoidExampleOnConstructors,
           ancestors,
           sourceCode
         );

src/rules/requireExample.js

@@ -12,11 +12,30 @@ export default iterateJsdoc(({
     tag: targetTagName
   });
 
+  if (utils.hasATag([
+    'inheritdoc',
+    'override'
+  ])) {
+    return;
+  }
+
+  if (utils.avoidExampleOnConstructors() && (
+    utils.hasATag([
+      'class',
+      'constructor'
+    ]) ||
+    utils.isConstructor()
+  )) {
+    return;
+  }
+
   if (_.isEmpty(functionExamples)) {
-    return report('Missing JSDoc @' + targetTagName + ' declaration.');
+    report('Missing JSDoc @' + targetTagName + ' declaration.');
+
+    return;
   }
 
-  return _.forEach(functionExamples, (example) => {
+  _.forEach(functionExamples, (example) => {
     const exampleContent = _.compact((example.name + ' ' + example.description).trim().split('\n'));
 
     if (_.isEmpty(exampleContent)) {

test/rules/assertions/requireExample.js

@@ -29,6 +29,37 @@ export default {
           message: 'Missing JSDoc @example description.'
         }
       ]
+    },
+    {
+      code: `
+      /**
+       * @constructor
+       */
+      function quux () {
+
+      }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @example declaration.'
+        }
+      ]
+    },
+    {
+      code: `
+      /**
+       * @constructor
+       * @example
+       */
+      function quux () {
+
+      }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @example description.'
+        }
+      ]
     }
   ],
   valid: [
@@ -67,6 +98,47 @@ export default {
 
           }
       `
+    },
+    {
+      code: `
+      /**
+       * @constructor
+       */
+      function quux () {
+
+      }
+      `,
+      settings: {
+        jsdoc: {
+          avoidExampleOnConstructors: true
+        }
+      }
+    },
+    {
+      code: `
+      /**
+       * @constructor
+       * @example
+       */
+      function quux () {
+
+      }
+      `,
+      settings: {
+        jsdoc: {
+          avoidExampleOnConstructors: true
+        }
+      }
+    },
+    {
+      code: `
+      /**
+       * @inheritdoc
+       */
+      function quux () {
+
+      }
+      `
     }
   ]
 };