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,
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
([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.
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() assumes that
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
transition.ease() also has the ability to accept such arguments and pass them to
Note: Looking at the interaction between
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.