update devDependencies, add jsdoc lint, fix lint issues

[squeep-api-dingus] / lib / content-negotiation.js

diff --git a/lib/content-negotiation.js b/lib/content-negotiation.js
index e78fe359303ae8bf2eb06902763ea2297f1baae4..fcf99adafcdb26f8e726a2203c9b4cfeca363346 100644 (file)
--- a/lib/content-negotiation.js
+++ b/lib/content-negotiation.js
@@ -7,12 +7,16 @@ const Enum = require('./enum');
 // A weight value smaller than the allowed resolution, for minute wildcard de-preferencing.
 const WeightIota = 0.0001;
 
+/**
+ * Methods for negotiating content types.
+ */
 class ContentNegotiation {
 
   /**
    * Convert accept clause string to object.
    * Adjust weight based on wildcards, to prefer literal matches.
-   * @param {string} clause 
+   * @param {string} clause portion of an accept header
+   * @returns {object|undefined} details of clause
    */
   static _unpackAcceptClause(clause) {
     let params = clause.split(';');
@@ -44,7 +48,8 @@ class ContentNegotiation {
 
   /**
    * Split an accept field into clauses, return list of clauses sorted by heaviest weights first.
-   * @param {string} acceptHeader 
+   * @param {string} acceptHeader collection of accept clauses
+   * @returns {object[]} array of clause details sorted by desirability
    */
   static _acceptClauses(acceptHeader) {
     const clauses = (acceptHeader||'').split(',')
@@ -56,8 +61,9 @@ class ContentNegotiation {
   /**
    * Check if an Accept-able Content-Type matches a fixed Content-Type.
    * (Allows for '*' fields in Accept-able type.)
-   * @param {string} pattern 
-   * @param {string} type 
+   * @param {string} acceptableType explicit or wildcard
+   * @param {string} fixedType explicit
+   * @returns {boolean} matches
    */
   static _matchType(acceptableType, fixedType) {
     acceptableType = common.splitFirst(acceptableType, '/', '*');
@@ -76,8 +82,9 @@ class ContentNegotiation {
 
   /**
    * Return the best match between available and acceptable types.
-   * @param {string[]} acceptableTypes
-   * @param {string} acceptHeader
+   * @param {string[]} acceptableTypes available types
+   * @param {string} acceptHeader accept header
+   * @returns {string|undefined} best matched type
    */
   static accept(acceptableTypes, acceptHeader) {
     const validTypesQuality = {};
@@ -113,7 +120,8 @@ class ContentNegotiation {
    * Return all viable matches between acceptable and requested encodings, ordered by highest preference first.
    * TODO: sort equal q-values by server-preference rather than header order
    * @param {string[]} acceptableEncodings e.g. ['br', 'gzip'] in order of server preference
-   * @param {string} acceptHeader 
+   * @param {string} acceptHeader encoding header
+   * @returns {string[]} preferred encoding
    */
   static preferred(acceptableEncodings, acceptHeader) {
     const Identity = Enum.EncodingType.Identity;