What’s the best approach to creating documentation (displaying the function prototype if you will) for functions that take a variety of different forms in terms of parameters.
Let’s say there are 10 different choices:
param(name);
param(name, type);
param(name, options);
param(name, type, options);
param(name, fn);
param(name, type, fn);
param(name, options, fn);
param(name, type, options, fn);
param(options);
param(options, fn);
How would one write a function prototype (documentation) for these types of methods (even ones that don’t come to this extreme)?
Some projects use function “overloading” in the documentation:
.on(event, fn, [capture])
.on(event, selector, fn, [capture])
But would the length be outweighed by the clarity or flexibility?
2
The reason projects use the overloading syntax is because it is easy and clear to read. There might be criticism about the jQuery library but it is one of the best documented libraries I know of in JavaScript, it’s very easy to read.
Functions in that syntax have two purposes, either arguments are optional (like passing options to $.get in jQuery) or arguments change what the function does (overloading). These two cases are fundamentally different!
See how for example in jQuery the .css function is divided into:
.css( propertyName ) // gets a property value
.css( propertyName, value ) //sets a property value
These perform fundamentally different tasks and need to be documented as different methods.
On the contrary the $.get method performs the same action but has optional prameters, which is why it is documented as such:
jQuery.get( url [, data ] [, success(data, textStatus, jqXHR) ] [, dataType ] )
This makes it clear to us that the action performed is fundamentally the same but optional parameters give us hints about what we may pass to the method.
2