fix: improves explanatory comments

Author: artem-zakharchenko

lib/units/coerce/index.js

@@ -7,11 +7,14 @@ const coercionMap = {
   headers: otherwise({})
 };
 
-// Coercion uses strict evolve to ensure the properties
-// set in expected schema are set on the result object,
-// even if not present in data object. This is what
-// coercion is about, in the end.
+// Coercion is strict by default, meaning it would populate
+// all the keys illegible for coercion on the given object,
+// even if those keys are missing.
 const coerce = evolve(coercionMap, { strict: true });
+
+// There is also a weak variant of coercion that operates
+// only on the present keys in the given object.
+// This is used for coercing expected HTTP message, for example.
 const coerceWeak = evolve(coercionMap);
 
 module.exports = {

lib/units/normalize/normalizeHeaders.js

@@ -3,9 +3,9 @@ const normalizeStringValue = (value) => {
 };
 
 /**
- * Normalizes the given headers.
- * @param {Object} headers
- * @returns {Object}
+ * Normalizes given headers.
+ * @param {Object<string, string>} headers
+ * @returns {Object<string, string>}
  */
 const normalizeHeaders = (headers) => {
   const headersType = typeof headers;

lib/units/normalize/normalizeMethod.js

@@ -1,6 +1,7 @@
 /**
- * Normalizes given HTTP message method.
+ * Normalizes given method.
  * @param {string} method
+ * @returns {string}
  */
 const normalizeMethod = (method) => {
   return method.trim().toUpperCase();

lib/units/normalize/normalizeStatusCode.js

@@ -1,3 +1,8 @@
+/**
+ * Normalizes given status code.
+ * @param {string} value
+ * @returns {string}
+ */
 function normalizeStatusCode(value) {
   return value == null ? '' : String(value).trim();
 }

lib/units/validateBody.js

@@ -60,9 +60,9 @@ function isJsonContentType(contentType) {
  * Returns a tuple of error and body media type based
  * on the given body and normalized headers.
  * @param {string} body
- * @param {Object} headers
- * @param {'real'|'expected'} bodyType
- * @returns {[error, bodyType]}
+ * @param {string} contentType
+ * @param {'real'|'expected'} httpMessageOrigin
+ * @returns {[string, MediaType]}
  */
 function getBodyType(body, contentType, httpMessageOrigin) {
   const hasJsonContentType = isJsonContentType(contentType);
@@ -90,7 +90,7 @@ ${parsingError.message}`
  * Returns a tuple of error and schema media type
  * based on given body schema.
  * @param {string} bodySchema
- * @returns {[error, schemaType]}
+ * @returns {[string, string]}
  */
 function getBodySchemaType(bodySchema) {
   const jsonSchemaType = mediaTyper.parse('application/schema+json');

lib/units/validateURI.js

@@ -5,6 +5,7 @@ const APIARY_URI_TYPE = 'text/vnd.apiary.uri';
 /**
  * Parses a given query string into an Object.
  * @param {string} queryString
+ * @returns {Object<string, string | string[]>}
  */
 const parseQueryString = (queryString) => {
   if (!queryString) {

lib/utils/otherwise.js

@@ -1,3 +1,7 @@
+/**
+ * Accepts a fallback value and returns an ensuring function
+ * that uses the fallback value in case real one is not provided.
+ */
 const otherwise = (fallbackValue) => (realValue) => {
   return realValue || fallbackValue;
 };

lib/validate.js

@@ -14,14 +14,16 @@ function validate(expectedMessage, realMessage) {
   };
 
   // Uses strict coercion on real message.
-  // Strict coercion ensures real message has properties illegible
-  // for validation with the expected message.
+  // Strict coercion ensures that real message always has properties
+  // illegible for validation with the expected message, even if they
+  // are not present in the real message.
   const real = normalize(coerce(realMessage));
 
   // Use weak coercion on expected message.
-  // This means that only the properties present in expected message
-  // will be coerced. We don't want to mutate user's assertion.
-  // However, we want to use the same coercion logic for any coercion type.
+  // Weak coercion will transform only the properties present in the
+  // expected message. Properties meant for coercion, but not provided
+  // in the expected message are left out, as we don't want to mutate
+  // user's assertion.
   const expected = normalize(coerceWeak(expectedMessage));
 
   if (expected.method) {