docs: use standard jsdoc tags everywhere (#677)

* docs: use standard jsdoc tags everywhere
* docs: fix jsdoc function return type annotation

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Phillip9587

index.js

@@ -7,26 +7,23 @@
 'use strict'
 
 /**
- * @typedef Parsers
- * @type {function}
- * @property {function} json
- * @property {function} raw
- * @property {function} text
- * @property {function} urlencoded
+ * @typedef {Object} Parsers
+ * @property {Function} json JSON parser
+ * @property {Function} raw Raw parser
+ * @property {Function} text Text parser
+ * @property {Function} urlencoded URL-encoded parser
  */
 
 /**
  * Module exports.
- * @type {Parsers}
+ * @type {Function & Parsers}
  */
-
 exports = module.exports = bodyParser
 
 /**
  * JSON parser.
  * @public
  */
-
 Object.defineProperty(exports, 'json', {
   configurable: true,
   enumerable: true,
@@ -37,7 +34,6 @@ Object.defineProperty(exports, 'json', {
  * Raw parser.
  * @public
  */
-
 Object.defineProperty(exports, 'raw', {
   configurable: true,
   enumerable: true,
@@ -48,7 +44,6 @@ Object.defineProperty(exports, 'raw', {
  * Text parser.
  * @public
  */
-
 Object.defineProperty(exports, 'text', {
   configurable: true,
   enumerable: true,
@@ -59,7 +54,6 @@ Object.defineProperty(exports, 'text', {
  * URL-encoded parser.
  * @public
  */
-
 Object.defineProperty(exports, 'urlencoded', {
   configurable: true,
   enumerable: true,
@@ -69,12 +63,9 @@ Object.defineProperty(exports, 'urlencoded', {
 /**
  * Create a middleware to parse json and urlencoded bodies.
  *
- * @param {object} [options]
- * @return {function}
  * @deprecated
  * @public
  */
-
 function bodyParser () {
   throw new Error('The bodyParser() generic has been split into individual middleware to use instead.')
 }

lib/read.js

@@ -28,15 +28,14 @@ module.exports = read
 /**
  * Read a request into a buffer and parse.
  *
- * @param {object} req
- * @param {object} res
- * @param {function} next
- * @param {function} parse
- * @param {function} debug
- * @param {object} options
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ * @param {Function} parse
+ * @param {Function} debug
+ * @param {Object} options
  * @private
  */
-
 function read (req, res, next, parse, debug, options) {
   if (onFinished.isFinished(req)) {
     debug('body already parsed')
@@ -176,13 +175,12 @@ function read (req, res, next, parse, debug, options) {
 /**
  * Get the content stream of the request.
  *
- * @param {object} req
- * @param {function} debug
- * @param {boolean} [inflate=true]
- * @return {object}
- * @api private
+ * @param {Object} req
+ * @param {Function} debug
+ * @param {boolean} inflate
+ * @returns {Object}
+ * @private
  */
-
 function contentstream (req, debug, inflate) {
   var encoding = (req.headers['content-encoding'] || 'identity').toLowerCase()
   var length = req.headers['content-length']
@@ -209,9 +207,9 @@ function contentstream (req, debug, inflate) {
 /**
  * Create a decompression stream for the given encoding.
  * @param {string} encoding
- * @param {function} debug
- * @return {object}
- * @api private
+ * @param {Function} debug
+ * @returns {Object}
+ * @private
  */
 function createDecompressionStream (encoding, debug) {
   switch (encoding) {
@@ -235,11 +233,10 @@ function createDecompressionStream (encoding, debug) {
 /**
  * Dump the contents of a request.
  *
- * @param {object} req
- * @param {function} callback
- * @api private
+ * @param {Object} req
+ * @param {Function} callback
+ * @private
  */
-
 function dump (req, callback) {
   if (onFinished.isFinished(req)) {
     callback(null)

lib/types/json.js

@@ -33,7 +33,6 @@ module.exports = json
  *            %x0A /              ; Line feed or New line
  *            %x0D )              ; Carriage return
  */
-
 var FIRST_CHAR_REGEXP = /^[\x20\x09\x0a\x0d]*([^\x20\x09\x0a\x0d])/ // eslint-disable-line no-control-regex
 
 var JSON_SYNTAX_CHAR = '#'
@@ -42,11 +41,10 @@ var JSON_SYNTAX_REGEXP = /#+/g
 /**
  * Create a middleware to parse JSON bodies.
  *
- * @param {object} [options]
- * @return {function}
+ * @param {Object} [options]
+ * @returns {Function}
  * @public
  */
-
 function json (options) {
   const normalizedOptions = normalizeOptions(options, 'application/json')
 
@@ -96,10 +94,9 @@ function json (options) {
  *
  * @param {string} str
  * @param {string} char
- * @return {Error}
+ * @returns {Error}
  * @private
  */
-
 function createStrictSyntaxError (str, char) {
   var index = str.indexOf(char)
   var partial = ''
@@ -128,10 +125,9 @@ function createStrictSyntaxError (str, char) {
  * Get the first non-whitespace character in a string.
  *
  * @param {string} str
- * @return {function}
+ * @returns {string|undefined}
  * @private
  */
-
 function firstchar (str) {
   var match = FIRST_CHAR_REGEXP.exec(str)
 
@@ -144,10 +140,10 @@ function firstchar (str) {
  * Normalize a SyntaxError for JSON.parse.
  *
  * @param {SyntaxError} error
- * @param {object} obj
- * @return {SyntaxError}
+ * @param {Object} obj
+ * @returns {SyntaxError}
+ * @private
  */
-
 function normalizeJsonSyntaxError (error, obj) {
   var keys = Object.getOwnPropertyNames(error)
 

lib/types/raw.js

@@ -23,11 +23,10 @@ module.exports = raw
 /**
  * Create a middleware to parse raw bodies.
  *
- * @param {object} [options]
- * @return {function}
- * @api public
+ * @param {Object} [options]
+ * @returns {Function}
+ * @public
  */
-
 function raw (options) {
   const normalizedOptions = normalizeOptions(options, 'application/octet-stream')
 

lib/types/text.js

@@ -23,11 +23,10 @@ module.exports = text
 /**
  * Create a middleware to parse text bodies.
  *
- * @param {object} [options]
- * @return {function}
- * @api public
+ * @param {Object} [options]
+ * @returns {Function}
+ * @public
  */
-
 function text (options) {
   const normalizedOptions = normalizeOptions(options, 'text/plain')
 

lib/types/urlencoded.js

@@ -27,11 +27,10 @@ module.exports = urlencoded
 /**
  * Create a middleware to parse urlencoded bodies.
  *
- * @param {object} [options]
- * @return {function}
+ * @param {Object} [options]
+ * @returns {Function}
  * @public
  */
-
 function urlencoded (options) {
   const normalizedOptions = normalizeOptions(options, 'application/x-www-form-urlencoded')
 
@@ -62,9 +61,10 @@ function urlencoded (options) {
 /**
  * Get the extended query parser.
  *
- * @param {object} options
+ * @param {Object} options
+ * @returns {Function}
+ * @private
  */
-
 function createQueryParser (options) {
   var extended = Boolean(options?.extended)
   var parameterLimit = options?.parameterLimit !== undefined
@@ -127,8 +127,8 @@ function createQueryParser (options) {
  *
  * @param {string} body
  * @param {number} limit
- * @return {number|undefined} Returns undefined if limit exceeded
- * @api private
+ * @returns {number|undefined} Returns undefined if limit exceeded
+ * @private
  */
 function parameterCount (body, limit) {
   let count = 0

lib/utils.js

@@ -20,10 +20,10 @@ module.exports = {
 /**
  * Get the charset of a request.
  *
- * @param {object} req
- * @api private
+ * @param {Object} req
+ * @returns {string | undefined}
+ * @private
  */
-
 function getCharset (req) {
   try {
     return (contentType.parse(req).parameters.charset || '').toLowerCase()
@@ -36,9 +36,9 @@ function getCharset (req) {
  * Get the simple type checker.
  *
  * @param {string | string[]} type
- * @return {function}
+ * @returns {Function}
+ * @private
  */
-
 function typeChecker (type) {
   return function checkType (req) {
     return Boolean(typeis(req, type))
@@ -48,9 +48,10 @@ function typeChecker (type) {
 /**
  * Normalizes the common options for all parsers.
  *
- * @param {object} options options to normalize
- * @param {string | string[] | function} defaultType default content type(s) or a function to determine it
- * @returns {object}
+ * @param {Object} options options to normalize
+ * @param {string | string[] | Function} defaultType default content type(s) or a function to determine it
+ * @returns {Object}
+ * @private
  */
 function normalizeOptions (options, defaultType) {
   if (!defaultType) {
@@ -89,7 +90,8 @@ function normalizeOptions (options, defaultType) {
  * Used by parsers that don't need to transform the data.
  *
  * @param {*} value
- * @return {*}
+ * @returns {*}
+ * @private
  */
 function passthrough (value) {
   return value