feat(require-jsdoc): support objects to contexts with a context and optional inlineCommentBlock property; fixes part of #530

`inlineCommentBlock` will cause the fixer to insert an inline jsdoc block instead of the regular multiline, indented block.

Author: brettz9

.README/rules/require-jsdoc.md

@@ -32,9 +32,13 @@ Accepts one optional options object with the following optional keys.
   - `FunctionExpression`
   - `MethodDefinition`
 
-- `contexts` - Set this to an array of strings representing the additional
-  AST contexts where you wish the rule to be applied (e.g., `Property` for
-  properties). Defaults to an empty array.
+- `contexts` - Set this to an array of strings or objects representing the
+  additional AST contexts where you wish the rule to be applied (e.g.,
+  `Property` for properties). If specified as an object, it should have a
+  `context` property and can have an `inlineCommentBlock` property which,
+  if set to `true`, will add an inline `/** */` instead of the regular,
+  multi-line, indented jsdoc block which will otherwise be added. Defaults
+  to an empty array.
 
 - `exemptEmptyFunctions` (default: false) - When `true`, the rule will not report
   missing jsdoc blocks above functions/methods with no parameters or return values

README.md

@@ -7837,9 +7837,13 @@ Accepts one optional options object with the following optional keys.
   - `FunctionExpression`
   - `MethodDefinition`
 
-- `contexts` - Set this to an array of strings representing the additional
-  AST contexts where you wish the rule to be applied (e.g., `Property` for
-  properties). Defaults to an empty array.
+- `contexts` - Set this to an array of strings or objects representing the
+  additional AST contexts where you wish the rule to be applied (e.g.,
+  `Property` for properties). If specified as an object, it should have a
+  `context` property and can have an `inlineCommentBlock` property which,
+  if set to `true`, will add an inline `/** */` instead of the regular,
+  multi-line, indented jsdoc block which will otherwise be added. Defaults
+  to an empty array.
 
 - `exemptEmptyFunctions` (default: false) - When `true`, the rule will not report
   missing jsdoc blocks above functions/methods with no parameters or return values
@@ -8293,6 +8297,14 @@ const hello = name => {
 export const loginSuccessAction = (): BaseActionPayload => ({ type: LOGIN_SUCCESSFUL });
 // Options: [{"require":{"ArrowFunctionExpression":true,"FunctionDeclaration":false}}]
 // Message: Missing JSDoc comment.
+
+export type Container = {
+  constants?: ObjByString;
+  enums?: { [key in string]: TypescriptEnum };
+  helpers?: { [key in string]: AnyFunction };
+};
+// Options: [{"contexts":["TSTypeAliasDeclaration",{"context":"TSPropertySignature","inlineCommentBlock":true}]}]
+// Message: Missing JSDoc comment.
 ````
 
 The following patterns are not considered problems:
@@ -10724,6 +10736,16 @@ const bboxToObj = function ({x, y, width, height}) {
   return {x, y, width, height};
 };
 // Options: [{"checkTypesPattern":"SVGRect"}]
+
+class CSS {
+  /**
+   * Set one or more CSS properties for the set of matched elements.
+   *
+   * @param {Object} propertyObject - An object of property-value pairs to set.
+   */
+  setCssObject(propertyObject: {[key: string]: string | number}): void {
+  }
+}
 ````
 
 

src/jsdocUtils.js

@@ -595,7 +595,11 @@ const enforcedContexts = (context, defaultContexts) => {
  */
 const getContextObject = (contexts, checkJsdoc) => {
   return contexts.reduce((obj, prop) => {
-    obj[prop] = checkJsdoc;
+    if (typeof prop === 'object') {
+      obj[prop.context] = checkJsdoc;
+    } else {
+      obj[prop] = checkJsdoc;
+    }
 
     return obj;
   }, {});

src/rules/requireJsdoc.js

@@ -10,7 +10,23 @@ const OPTIONS_SCHEMA = {
   properties: {
     contexts: {
       items: {
-        type: 'string',
+        anyOf: [
+          {
+            type: 'string',
+          },
+          {
+            additionalProperties: false,
+            properties: {
+              context: {
+                type: 'string',
+              },
+              inlineCommentBlock: {
+                type: 'boolean',
+              },
+            },
+            type: 'object',
+          },
+        ],
       },
       type: 'array',
     },
@@ -89,10 +105,16 @@ const getOption = (context, baseObject, option, key) => {
 };
 
 const getOptions = (context) => {
+  const {
+    publicOnly,
+    contexts = [],
+    exemptEmptyFunctions = false,
+  } = context.options[0] || {};
+
   return {
-    exemptEmptyFunctions: context.options[0] ? context.options[0].exemptEmptyFunctions : false,
+    contexts,
+    exemptEmptyFunctions,
     publicOnly: ((baseObj) => {
-      const publicOnly = _.get(context, 'options[0].publicOnly');
       if (!publicOnly) {
         return false;
       }
@@ -122,7 +144,11 @@ export default {
     const sourceCode = context.getSourceCode();
     const settings = getSettings(context);
 
-    const {require: requireOption, publicOnly, exemptEmptyFunctions} = getOptions(context);
+    const {
+      require: requireOption,
+      contexts,
+      publicOnly, exemptEmptyFunctions,
+    } = getOptions(context);
 
     const checkJsDoc = (node, isFunctionContext) => {
       const jsDocNode = getJSDocComment(sourceCode, node, settings);
@@ -149,7 +175,13 @@ export default {
             baseNode.loc.start.column,
           ),
         });
-        const insertion = `/**\n${indent}*\n${indent}*/${'\n'.repeat(lines)}${indent.slice(0, -1)}`;
+        const {inlineCommentBlock} = contexts.find(({context: ctxt}) => {
+          return ctxt === node.type;
+        }) || {};
+        const insertion = (inlineCommentBlock ?
+          '/** ' :
+          `/**\n${indent}*\n${indent}`) +
+            `*/${'\n'.repeat(lines)}${indent.slice(0, -1)}`;
 
         return fixer.insertTextBefore(baseNode, insertion);
       };

test/rules/assertions/requireJsdoc.js

@@ -1911,6 +1911,54 @@ export default {
         sourceType: 'module',
       },
     },
+    {
+      code: `
+      export type Container = {
+        constants?: ObjByString;
+        enums?: { [key in string]: TypescriptEnum };
+        helpers?: { [key in string]: AnyFunction };
+      };
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.',
+        },
+        {
+          message: 'Missing JSDoc comment.',
+        },
+        {
+          message: 'Missing JSDoc comment.',
+        },
+        {
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          contexts: [
+            'TSTypeAliasDeclaration',
+            {
+              context: 'TSPropertySignature',
+              inlineCommentBlock: true,
+            },
+          ],
+        },
+      ],
+      output: `
+      /**
+       *
+       */
+      export type Container = {
+        /** */
+        constants?: ObjByString;
+        /** */
+        enums?: { [key in string]: TypescriptEnum };
+        /** */
+        helpers?: { [key in string]: AnyFunction };
+      };
+      `,
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
   ],
   valid: [{
     code: `