Brian B Brian B - 4 months ago 13
Javascript Question

JavaScript API documentation - what does functionName([value[, arguments]]) notation mean?

This question is related to: How to read API documentation for newbs?. However, that question does not cover the specific format I am asking about here where there are nested brackets (for example,

[value[, args]]
).

Although, I presume this could relate to any API, I'm looking at the D3.js API, specifically
transition.ease()
. I cannot figure out what the following means:

transition.ease([value[, arguments]])


It's difficult to find out, as I don't know what search terms to Google! I just want to know:


  1. How it is suppose to be read?

  2. Is it a general/normal notation?



I know how to use that D3 function; it's just the notation I'm interested in.

Answer

The documentation for transition.ease([value[, arguments]]) appears to make it relatively clear what they are attempting to say. In addition, it follows the "normal" syntax for methods of having optional arguments in [].

In this case, it means that ease() is a method of transition. For the ease() method: ([value[, arguments]]), means passing any arguments is optional. Then, value[, arguments] is intended to mean that if the value argument is present, then an unrestricted number of additional arguments may optionally be present. I say "intended to mean" because normally being able to have multiples of an argument is indicated using an ellipse .... Thus, that would normally be: value[, arguments...]. From looking further at the documentation, it is clear that this is what was intended.

Parsing the documentation (additional formatting by me):

Specifies the transition easing function.

If value is a function, it is used to ease the current parametric timing value t, which is typically in the range [0,1]. (At the end of a transition, t may be slightly greater than 1.)

You can pass a function as the argument to transition.ease(). If you do, then it is used as the function to determine how the transition occurs.

Otherwise, value is assumed to be a string and the arguments are passed to the d3.ease method to generate an easing function. The default easing function is "cubic-in-out". Note that it is not possible to customize the easing function per-element or per-attribute; however, if you use the "linear" easing function, you can apply custom easing inside your interpolator using attrTween or styleTween.

If value is not a function, it is assumed that you are going to use d3.ease() as the transition function. In which case, all the arguments to transition.ease() are passed to d3.ease(). d3.ease() assumes that value (called type in the d3.ease() write-up) is a string. d3.ease(type[, arguments…]) has the ability to take additional optional arguments. In order for you to specify any additional arguments you desire to the d3.ease() function, transition.ease() also has the ability to accept such arguments and pass them to d3.ease().

Note: Looking at the interaction between transition.ease() and d3.ease() is where we see that transition.ease([value[, arguments]]) really should have been written with the ellipse as transition.ease([value[, arguments..]]). If that is not the intended use, then the described interaction with d3.ease() would not make sense.

If ease is not specified, returns the easing function bound to the first non-null element in the transition.

This is actually not clear. I expect that it contains a mistake in that "ease" should be "value". In which case it would read:

If value is not specified, returns the easing function bound to the first non-null element in the transition.

If this is actually what was intended, then not specifying any arguments to transition.ease() will result in getting back as a returned value the easing function which is bound to the first non-null element in the transition. This would be a normal and expected use of not supplying any arguments to such a function. Thus, I consider that it is quite likely that this issue really is a mistake in the documentation. This could be verified by either looking in the source code, or by experimentation.