documentationjs / documentationjs/documentation

@param should have final say if a parameter is optional or has a default

Open
#1,088 2 comments 2 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

A the moment, this:

```js
/**
* An example.
* @param {Object} options Options.
* @param {FooOptions} options.fooOptions Foo options.
* @param {BarOptions} options.barOptions Bar options.
*/
const example = ({ fooOptions, barOptions } = {}) =>
compose(foo(fooOptions), bar(barOptions))
```

Incorrectly renders with options being optional, due to the JS `= {}` syntax taking priority over the `@param`:

screen shot 2018-06-05 at 12 52 14 am

In this example the user must provide options to the `example` function, because the `foo` and `bar` function options are non-optional. The `= {}` is only there for more elegant error handling by allowing validation to happen inside `foo` and `bar`.

* What version of documentation.js are you using?: v7.1.0
* How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.