Javascript: Understanding function syntax and parameters

Question

I am trying to make sense of the onchange event of bootstrap-multiselect . In particular, I am trying to understand the function syntax and parameters.

$('#example-onChange').multiselect({
     onChange: function(option, checked, select) {
            alert('Changed option ' + $(option).val() + '.');
           }
});

How to know what does the three parameters in the function mean? Where will I get these three parameters? I also tried looking at the code https://github.com/davidstutz/bootstrap-multiselect/blob/master/dist/js/bootstrap-multiselect.js#L263 but couldn't make much sense of it.

I know using alerts that in this function option refers to the selected option, checked shows whether the option was checked or unchecked . I keep getting undefined when doing console.log(select) inside the function, so not sure what does that mean.

Question : How to understand function parameters and syntax like these? This is just an example but knowing a generic procedure will help me decode other similar functions in future.

Answer 1

In short, it seems the library doesn't actually provide the select option.

---

In general, in situations where the documentation isn't very precise, the technique I often apply is to console.log the arguments , then inspecting what each of them look like.

In this situation, when doing:

$('#example-onChange').multiselect({
    onChange: function(option, checked, select) {
        console.log(arguments);
    }
});

... I got the following output:

... from this you can see two arguments are provided. The first is the jQuery object of the option that was clicked. The second (you can assume) is a boolean as to whether the option is selected or not.

You can also see no select (3rd argument) was provided.

---

Another approach you can take is to search the source code, like you did; but I'd recommend finding where the function was called , rather than where it was defined. By searching for onChange in the source code , you can see onChange is called at least 3 times.

1. this.options.onChange($option, checked);
2. this.options.onChange($option, true);
3. this.options.onChange($option, false);

... none of which provide a 3rd argument. I say at least 3 times here , because it can be hard sometimes (particularly in large libraries) to find all call sites, since developers can mask them in all sorts of weird and wonderful ways

---

Other techniques you can use:

1. Setting a breakpoint within your handler function (either using the "breakpoint" functionality of your dev. tools, or via the debugger statement), triggering the handler, then following the callstack (again, using developer tools) to examine the call site, and to see what variables are provided.

2. Opening an issue on the respective GitHub project. You'll find plenty of library owners are more than happy to help.

Answer 2

Unfortunatly, all Javascript libraries must have a very robust documentation.

Moreover, Javascript is a dynamically typed language, so there is no informations about the required types for the formal parameters. It make libraries more difficult to understand without good documentation.

In order to quickly understanding, with experience, there is some thinking mecanisms which can be used. For example, the parameters of an event's delegate provide informations on the elements on which it occurs. It's like these parameters are values returned to you.

In your example, there is chance that option, checked and select are concerned by the option's element in the multiselect defined in #example-onChange which was changed (onChange).

Example 1 :

onClose:function(success)
{
    //TODO
}

In this case, "success" should mean : this parameter is true if closing on my element has succeeded else "success" is false.

Example 2 :

afterSave:function(success, filename) {

}

In this case, "filename" should be the filename of the saved element after perform save's action.

I doing my best for writting correct english, I hope it's understandable.