Tim Roberts Tim Roberts - 2 months ago 7
Javascript Question

How to properly comment a partially applied function?

Given the following function:

const sameCharactersAs = a=> b => a.toLowerCase() === b.toLowerCase()


or

function sameCharactersAs(a){
return function(b){
return a.toLowerCase() === b.toLowerCase()
}
}


how would I write the documentation comment above it? How I am currently doing it is:

/**
* checks if the strings have the same characters in the same order
*
* @param {String} a first string to check
* @return {Function} takes second string to check
* @return {Bool}
*/


but I feel like having two returns isn't correct and not saying what the returned function expects doesn't seem right either. Any rules here or is it just a style preference?

Answer

I feel like having two returns isn't correct

Indeed not, a function has only one return value and JSDoc will expect only a single @return. Just say what it actually does:

/**
 * Creates a function to test strings against the given string to see whether
 * they contain the same characters in the same order (case insensitive).
 *
 * @param  {String} a   The string
 * @return {Function}   A function that accepts a second string and returns `true`
 *                      if the second string matches the given string `a` (case
 *                      insensitive) or `false` if it doesn't
 */