Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
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 –  Robert Harvey Apr 25 '13 at 23:17
1  
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 –  Zirak Apr 25 '13 at 23:18
add comment

1 Answer

up vote 5 down vote accepted

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.

share|improve this answer
    
@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. –  Benjamin Gruenbaum Apr 25 '13 at 23:24
    
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. –  Florian Margaine Apr 26 '13 at 6:28
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.