Documenting Function That Takes Random Parameters?

Question

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?

• Robert Harvey: How else would you do it? Write a function prototype for each overload. That's how Microsoft does it: msdn.microsoft.com/en-us/library/bb357126.aspx
• Zirak: I'd argue that such a function needs to re-thought of - either split into several ones if each "overload" is a bit different, or choose an argument pattern and stick with it

Answer 1

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.

• Benjamin Gruenbaum: @RobertHarvey You are correct, I may have over-addressed the issue, I changed the phrasing to be a lot more subtle. The criticism is mainly about bloat, inconsistency and having hard-to-read code, the latter lead to development of libraries like zeptojs.com which believe they are more readable. I'd like to avoid the issue of jQuery being good or bad, I think there is no argument about it being one of the best documented APIs.
• Florian Margaine: I'd argue over the "very easy to read" part, especially when you have 20 lines to handle the random arguments, all done through ternary operators. Sure, hopefully the documentation is there, but code should be self-documented.