API signature style

[dy]

We are using ES6-arguments signature style for API in docs now do(what, how?), e.g. in audio-buffer-utils:

util.normalize(buffer, target?, start=0, end=-0)

But is it clear enough?

More conventional MDN practice, following the NetBSD user message style would be do(what [, how])

util.normalize(buffer [, target] [, start] [, end])

That is less explanatory though, especially in case if we have options or functions as arguments, like

convert(source, {from, to}?, (error, data) => {}) vs convert(source [, options], callback).

But same time do we need that explanation in signature? Maybe it is enough having "rough outline" of arguments and then explain all the details, which bloats up readme usually. Anyways I am afraid can be horribly wrong opting for ES6-style description.

Any thoughts?

@jamen @connorhartley @ahdinosaur @danigb

[jamen]

I like the first way. I used to do the boxed way, but switched because I liked the style I saw in audio.js and friends. I think its worth having the little indicator in the signature, along with an explanation if necessary.

[ahdinosaur]

i like the first way using es6 notation. but personally dislike positional arguments, much prefer (options) => thing or (options, callback) => { callback(err, thing) }. with positional arguments you always have to reference the documentation to figure out what is happening, whereas an object is much more self-documenting.

[dy]

@ahdinosaur although named arguments are easier for reader, it does not obviate the need to look into docs to recall the names, whereas conventional positional arguments don't need that and sometimes not the less explanatory.

The case of very basic conventions:

list.slice(0, 10)
// vs
list.slice({from: 0, to: 10})
list.slice({start: 0, end: 10})

The case of "spatial" context of the method:

leftPad(str, 10, '0')
// vs
leftPad({
  source: str, //is it string? src? input? source?
  width: 10, //is it length? size? width?
  symbol: '0' //is it filler? fill? char? symbol?
})

Positional arguments avoid this way "see word - recall the meaning - apply in the context" via spatial memory (not the less ancient part of the brain). But I agree that for most non-trivial cases named params are better.

[dy]

Ok, thanks for the opinions, will use the first.