feat(builder): Describe optional columnList arg to with/Recurisve [knex/knex#4514]

[jeremy-w]

These are the documentation updates to accompany knex/knex#4652, to resolve knex/knex#4514.

I'm not 100% I got the notation right; I'm not clear on whether it's [whatever] to signal an array vs [whatever] to signal an optional argument. But I hope the examples make the meaning clear.

[kibertoad]

@jeremy-w We've used [] for optional parameters, and for arrays we used plural form in the name of a parameter.

[kibertoad]

just columns should be fine, if it is a mandatory array param

[jeremy-w]

Both with(alias, query) and with(alias, columns, query) are valid. It sounds like [columns] would be the way to write it though, without the star?

[kibertoad]

yup, fair

[kibertoad]

btw, wouldn't it be more correct to say that third parameter is optional, and second one could be either columns, or whatever third parameter could be as well?

[jeremy-w]

I think it’s equally correct, but I worry it obscures the intended behavior due to the complexity of the type signature:

with(alias, columns | (qb|callback|raw), (qb|callback|raw) | undefined)

The simplest way to document this IMO would be as two functions with different arities - which is how the TypeScript types are written, in fact. I don’t know that the documentation generator supports that notion of overloaded functions directly, though?

[kibertoad]

I doubt it, so your original format might be better

[jeremy-w]

Updated to use the [columns] styling of the optional column list.