It's very common in javascript to have the following:
function A (options, aaa, bbb) {
var ccc = options.ccc;
var ddd = options.ddd;
}
And currently I'm commenting it as such:
/**
* a completely useless function
*
* @param {Object} options where options.ccc is {Number} ccc and options.ddd is {String} ddd
* @param {Boolean} aaa
* @param {String} bbb
*/
I'm unhappy with the way I describe the attributes in the options parameter
Is there a clean way to put them in the "{Type} description" pattern?
I usually put a TAB or two after the variable's name ... before the description. I agree though... I'm not a huge fan either. But, this is how jsdocs processes it. If you fuddle with the formatting too much you may not get proper docs parsed out.
/**
* SLP.Modules.Codes extends the SLP.Modules object on DOM-ready.
* @module Codes
*/
SLP.Modules.Codes = {
/**
* First validate for empty fields, then check the campaign codes,
* making sure that they begin with T(oyota), L(exus), or S(cion).
* @param {object} event jQuery Event object (form submit)
* @return {boolean} true if all validation passes.
*/
validateCampaignCodes: function(event){
var $input, isValid = SLP.validateFormInputsNotEmpty(event);
if (isValid) {// Continue validation if all fields are non-empty.
$input = $("input").filter("[name=campaign_code]").each(function(){
if (!(isValid = /^[TLS]/i.test(this.value))) {
return !SLP.DOM.$modalPrompt.find(".modal-body").html( // Error msg.
"Campaign Codes must begin with T(oyota), S(cion), or L(exus)."
).end().modal("show");// On error, immediately exit (the each method).
}
});
}
// Convert campaign codes to uppercase for submission.
$input.val(function(i,v){ return v.toUpperCase(); });
// Enable all checkboxes to submit values with form.
$("input[type=checkbox]").attr("disabled", false);
return isValid;
},