javascript - 注释嵌套参数

Question

在 JavaScript 中，以下内容很常见:

function A (options, aaa, bbb) {
  var ccc = options.ccc;
  var ddd = options.ddd;
}

目前我是这样评论的:

/**
 * 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
 */

我对选项参数中描述属性的方式不满意

有没有一种干净的方法将它们放入“{Type}描述”模式中？

Answer 1

我通常在变量名称后面...描述之前放置一个或两个制表符。不过我同意......我也不是一个 super 粉丝。但是，这就是 jsdocs 处理它的方式。如果您过多地处理格式，您可能无法解析出正确的文档。

/**
 * 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;
    },