style: Require jsdoc/valid-types and jsdoc/check-param-names (newrelic#3368)

Author: amychisholm03

eslint.config.js

@@ -45,6 +45,12 @@ const newrelicConfigOverrides = {
 }
 
 const jsdocConfig = {
+  settings: {
+    jsdoc: {
+      // This is explicity set, so we don't get TypeScript-specific linting errors.
+      mode: 'jsdoc'
+    }
+  },
   plugins: { jsdoc },
   rules: {
     'jsdoc/require-jsdoc': 'off',
@@ -66,7 +72,9 @@ const jsdocConfig = {
           'EventEmitter'
         ]
       }
-    ]
+    ],
+    'jsdoc/valid-types': 'error',
+    'jsdoc/check-param-names': 'error'
   }
 }
 const jsdocOverrides = {

lib/collector/parse-response.js

@@ -16,18 +16,15 @@ const logger = require('../logger').child({ component: 'new_relic_response' })
  * about errors as possible, and to parse out the return value as often
  * as possible.
  *
- * @param string         name     Remote method name that was invoked.
- * @param ServerResponse response HTTP response stream
- * @param Function       callback Function that will be called with any
- *                                error, the value returned by the server
- *                                (if any), and the raw JSON of the
- *                                server's response.
- * @param name
- * @param response
- * @param callback
- * @returns Function Another callback that is meant to be invoked with
- *                   any errors from reading the response stream, as
- *                   well as a string containing the full response.
+ * @param {string}         name     Remote method name that was invoked.
+ * @param {ServerResponse} response HTTP response stream
+ * @param {Function}       callback Function that will be called with any
+ *                                  error, the value returned by the server
+ *                                  (if any), and the raw JSON of the
+ *                                  server's response.
+ * @returns {Function} Another callback that is meant to be invoked with
+ *                     any errors from reading the response stream, as
+ *                     well as a string containing the full response.
  */
 module.exports = function parse(name, response, callback) {
   if (!callback) {

lib/collector/remote-method.js

@@ -128,9 +128,8 @@ RemoteMethod.prototype.invoke = function invoke(payload, nrHeaders, callback) {
  * Take a serialized payload and create a response wrapper for it before
  * invoking the method on the collector.
  *
- * @param {string}   methodName Name of method to invoke on collector.
  * @param {string}   data       Serialized payload.
- * @param {?object}  nrHeaders  NR request headers from connect response.
+ * @param {object}  nrHeaders  NR request headers from connect response.
  * @param {Function} callback   What to do next. Gets passed any error.
  */
 RemoteMethod.prototype._post = function _post(data, nrHeaders, callback) {
@@ -282,6 +281,7 @@ RemoteMethod.prototype._safeRequest = function _safeRequest(options) {
  * Generate the request headers and wire up the request. There are many
  * parameters used to make a request:
  *
+ * @param options
  * @param {string}   options.host       Hostname (or proxy hostname) for collector.
  * @param {string}   options.port       Port (or proxy port) for collector.
  * @param {string}   options.path       URL path for method being invoked on collector.
@@ -292,7 +292,6 @@ RemoteMethod.prototype._safeRequest = function _safeRequest(options) {
  *                                      original callback given to .send).
  * @param {Function} options.onResponse Response handler for this request (created by
  *                                      ._post).
- * @param options
  */
 RemoteMethod.prototype._request = function _request(options) {
   const requestOptions = {

lib/config/formatters.js

@@ -10,7 +10,7 @@ const formatters = module.exports
  * Splits a string by a ',' and trims whitespace
  *
  * @param {string} val config setting
- * @param {Array}
+ * @returns {Array}
  */
 formatters.array = function array(val) {
   return val.split(',').map((k) => k.trim())
@@ -39,8 +39,7 @@ formatters.float = function float(val) {
 /**
  * Parses a config setting as a boolean
  *
- * @param {string} val config setting
- * @param setting
+ * @param {string} setting value of config setting
  * @returns {boolean}
  */
 formatters.boolean = function boolean(setting) {

lib/instrumentation/core/http-outbound.js

@@ -289,8 +289,7 @@ function applySegment({ opts, makeRequest, host, port, hostname, segment, config
  * events.
  *
  * @param {Agent} agent New Relic agent
- * @param {string} hostname host of outbound request
- * @param host
+ * @param {string} host host of outbound request
  * @param {TraceSegment} segment outbound http segment
  * @param {http.IncomingMessage} request actual http outbound request
  */

lib/metrics/normalizer.js

@@ -88,9 +88,8 @@ util.inherits(MetricNormalizer, EventEmitter)
  * Convert the raw, de-serialized JSON response into a set of
  * NormalizationRules.
  *
- * @param object json The de-serialized JSON response sent on collector
+ * @param {object} json The de-serialized JSON response sent on collector
  *                    connection.
- * @param json
  */
 MetricNormalizer.prototype.load = function load(json) {
   if (json) {

lib/shim/datastore-shim.js

@@ -500,7 +500,7 @@ function captureInstanceAttributes(host, port, database) {
 /**
  * Parses the database name from a `USE` SQL query.
  *
- * @memberof DatastoreShim.prototype
+ * @this DatastoreShim
  * @param {string} query - The SQL query to parse the database name from.
  * @returns {?string} The name of the database if it could be parsed, otherwise
  *  `null`.

lib/shim/message-shim/subscribe-consume.js

@@ -38,7 +38,6 @@ function _nameMessageTransaction(shim, msgDesc) {
  * @param {Function} params.fn subscriber function
  * @param {specs.MessageSubscribeSpec} params.spec spec for subscriber
  * @param params.name
- * @param {boolean} params.destNameIsArg flag to state if destination is an argument
  * @returns {Function} wrapped subscribe function
  */
 function createSubscriberWrapper({ shim, fn, spec, name }) {

lib/shim/promise-shim.js

@@ -366,9 +366,7 @@ function _wrapExecutorContext(shim, args) {
 
   /**
    *
-   * @param {Function} resolve function of promise
-   * @param {Function} reject function of promise
-   * @param {...any} args
+   * @param {Object} args contains the `resolve` and `reject` functions of a promise
    */
   function contextExporter(...args) {
     const [resolve, reject] = args

lib/shim/shim.js

@@ -1453,8 +1453,7 @@ function isPromise(obj) {
  * promise or async function
  *
  * @memberof Shim.prototype
- * @param fn
- * @param (function) function to test if async
+ * @param {function} fn function to test if async
  * @returns {boolean} True if the function is an async function
  */
 function isAsyncFunction(fn) {
@@ -1871,8 +1870,8 @@ function _makeBindWrapper(shim, func, context, full) {
  * (i.e. `bindRowCallbackSegment` for `rowCallback`), but will fall back to the
  * generic callback binding method, `bindCallbackSegment`, otherwise.
  *
- * @this *
  * @private
+ * @this *
  * @param {Shim} shim
  *  The shim performing this binding.
  * @param {Function} fn