style: Require jsdoc check*, implements-on-classes, and some no-undefined-types (newrelic#3404)

Author: amychisholm03

eslint.config.js

@@ -56,28 +56,37 @@ const jsdocConfig = {
     // General rules
     'jsdoc/require-jsdoc': 'off',
     'jsdoc/tag-lines': 'off',
+    'jsdoc/check-tag-names': 'error',
+    'jsdoc/check-access': 'error',
+    'jsdoc/implements-on-classes': 'error',
     // Types rules
     'jsdoc/check-types': 'error',
-    'jsdoc/valid-types': 'error',
     'jsdoc/no-undefined-types': [
       'warn',
       {
         definedTypes: [
-          'Logger',
           'Agent',
-          'Shim',
-          'MessageShim',
-          'TraceSegment',
-          'Transaction',
-          'Tracer',
+          'Context',
+          'EventEmitter',
           'Exception',
+          'Logger',
+          'MessageShim',
           'MetricAggregator',
           'Metrics',
-          'EventEmitter',
-          'Context'
+          'OperationSpec',
+          'Segment',
+          'Shim',
+          'Spec',
+          'Trace',
+          'TraceSegment',
+          'Tracer',
+          'Transaction',
+          'QuerySpec',
+          'WebFrameworkShim'
         ]
       }
     ],
+    'jsdoc/valid-types': 'error',
     // Parameter rules
     'jsdoc/require-param-description': 'error',
     'jsdoc/check-param-names': 'error',
@@ -98,7 +107,8 @@ const jsdocOverrides = {
     'api.js'
   ],
   rules: {
-    'jsdoc/require-jsdoc': 'warn'
+    // Public-facing functions should always have jsdoc
+    'jsdoc/require-jsdoc': 'error'
   }
 }
 

lib/config/index.js

@@ -1530,7 +1530,7 @@ function _laspReponse(keys) {
  * Applies the server side LASP policies to a local configuration object
  *
  * @param {Agent} agent Agent instance
- * @param {bject} policies server side LASP policy
+ * @param {object} policies server side LASP policy
  * @returns {object} { missingRequired, finalPolicies } list of missing required fields and finalized LASP policy
  */
 Config.prototype._buildLaspPolicy = function _buildLaspPolicy(agent, policies) {

lib/metrics/recorders/database-operation.js

@@ -12,13 +12,12 @@ const metrics = require('../names')
  *
  * - `recordOperationMetrics(segment [, scope])`
  *
+ * This function is an implementation of {@link MetricFunction} (see #agentlib/shim/shim.js)
  * @private
- * @this DatastoreShim
- * @implements {MetricFunction}
  * @param {TraceSegment}  segment - The segment being recorded.
  * @param {string}        [scope] - The scope of the segment.
+ * @param {Transaction}   transaction - The transaction associated with the segment.
  * @see DatastoreShim#recordOperation
- * @see MetricFunction
  */
 function recordOperationMetrics(segment, scope, transaction) {
   const duration = segment.getDurationInMillis()

lib/shim/message-shim/consume.js

@@ -20,8 +20,8 @@ module.exports = createRecorder
  * @param {string} params.fnName name of function
  * @param {Array} params.args arguments passed to original consume function
  * @param {object} params.ctx this binding of the original function
- * @param {specs.MessageSpec} params.spec spec for the wrapped consume function
- * @returns {specs.MessageSpec} new spec
+ * @param {MessageSpec} params.spec spec for the wrapped consume function
+ * @returns {MessageSpec} new spec
  */
 function updateSpecFromArgs({ shim, fn, fnName, args, spec, ctx }) {
   let msgDesc = null

lib/shim/promise-shim.js

@@ -382,7 +382,6 @@ function _wrapExecutorContext(shim, args) {
  * @param {object} context context object
  * @param {Function} fn function that is wrapped
  * @returns {Function} wrapped function
- * @private
  */
 function _wrapResolver(context, fn) {
   return function wrappedResolveReject(val) {

lib/shim/shim.js

@@ -242,12 +242,12 @@ Shim.prototype[symbols.unwrap] = unwrapAll
  */
 
 /**
+ * Measures all the necessary metrics for the given segment. This functionality
+ * is meant to be used by Shim subclasses; instrumentations should never create
+ * their own recorders.
+ *
  * @private
  * @callback MetricFunction
- * @summary
- *  Measures all the necessary metrics for the given segment. This functionality
- *  is meant to be used by Shim subclasses, instrumentations should never create
- *  their own recorders.
  * @param {TraceSegment}  segment - The segment to record.
  * @param {string}        [scope] - The scope of the recording.
  */
@@ -1239,7 +1239,7 @@ function applyContext({ func, context, full, boundThis, args, inContextCB }) {
   this.logger.trace('Applying segment %s', segment.name)
 
   /**
-   *
+   * Callback to be run in the context of the segment.
    */
   function runInContextCb() {
     if (typeof inContextCB === 'function') {

lib/shim/webframework-shim/index.js

@@ -339,12 +339,21 @@ function savePossibleTransactionName(req) {
   }
 }
 
+/**
+ * Predicate used to determine whether a middleware invocation constitutes a response.
+ *
+ * @typedef {Function} ResponsePredicate
+ * @param {object[]} args - The arguments passed into the middleware.
+ * @param {object} res - The value returned from the middleware (if any).
+ * @returns {boolean} True if the invocation should be considered a response.
+ */
+
 /**
  * Sets a function to call with the result of a middleware to determine if it has
  * responded.
  *
  * @memberof WebFrameworkShim.prototype
- * @param {function(args, object): boolean} pred
+ * @param {ResponsePredicate} pred
  *  Function which should return true if the object passed to it is considered
  *  a response.
  */

lib/spans/span-context.js

@@ -41,7 +41,7 @@ class SpanContext {
    *
    * Last error wins.
    *
-   * @param {Obejct} details error details
+   * @param {object} details error details
    */
   setError(details) {
     this.hasError = true

lib/spans/streaming-span-event.js

@@ -224,7 +224,7 @@ class StreamingHttpSpanEvent extends StreamingSpanEvent {
  * Currently designed to be sent over grpc via the v1.proto definition.
  *
  * @private
- * @class.
+ * @class
  */
 class StreamingDatastoreSpanEvent extends StreamingSpanEvent {
   /**

lib/transaction/trace/segment.js

@@ -246,7 +246,7 @@ function _setExclusiveDurationInMillis(duration) {
  * The duration of the transaction trace tree that only this level accounts
  * for.
  *
- * @returns {integer} The amount of time the trace took, minus any child
+ * @returns {number} The amount of time the trace took, minus any child
  *                   segments, in milliseconds.
  */
 TraceSegment.prototype.getExclusiveDurationInMillis = getExclusiveDurationInMillis