Turn optional parameters (even different overloads?) into square-bracket-heading text

[wooorm]

Take for example:

### `raw(tree, options)`

Pass a hast tree through an HTML parser, which will fix nesting, and turn
raw nodes into actual nodes.

###### Parameters

* `tree` (`Root | RootContent`)
  — original hast tree to transform
* `options?` (`Options | null | undefined`)
  — configuration (optional)

The heading could be turned into:

### `raw(tree, options?)`

Or:

### `raw(tree[, options])`

[wooorm]

@remcohaszing I do wonder about this syntax though, doesn’t the options in raw(tree, options) kinda imply this already? Wouldn’t it be better to read the full docs on this function if you want to know whether something is optional? Especially the [ ] syntax is loosely inspired from C, perhaps that’s too archaic to be very useful now?

[remcohaszing]

What do you mean by doesn’t the options in raw(tree, options) kinda imply this already?

I personally don’t have a strong preference between

### `raw(tree, options?)`

or

### `raw(tree[, options])`

I recall having seen a Twitter poll about this not too long ago where a significant majority voted for raw(tree, options?). I don’t have a link though.

[wooorm]

The word “options” implies optionality.

[remcohaszing]

I see your point. However, although this is common, not all optional parameters have such a name, and options can be required.

[wooorm]

Definitely, but then you can also extend such reasoning to what “optional” even is: some things should almost always be given while technically optional. How useful is this question-mark / square-bracket syntax even? Does the parameter name infer the most useful info? And is that enough?