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

[jaydenseric]

A the moment, this:

/**
 * 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:

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

[tmcw]

The more general problem is a fair bit tricker than this example lets on:

• If you do want to mark something as optional, do you have to repeat the default value, or does [foo=] tell the engine that it should actually be optional? This would be default-param + optional-comment = use default param, show as optional
• Or should it be the inverse, that you should specify a type as non-nullable, like {Object!}, in which case default-param = use default param, show as optional && default-param + non-nullable = show as required

I'm open to (PRs of) either, though I do wish that (and in the future, plan to write a doc syntax successor that) has a clearer delineation of control than this, much like Flow is able to do.

[Berkmann18]

It also occurs on v10.1.0 where a param which has a default value (which is an Error to force the user to provide a value) but isn't optional (as indicated by the JSDoc doclet) but the generated docs say they are optional.

Example:

/**
 * ...
 * @param {Object<string>} param Parameters
 * @param {string} param.tag Tag of the commit message
 * @param {string} param.msg Header of the commit message
 * @param {string} param.convention Name of the commit convention
 */
const commitConv = ({
  tag = required('tag'),
  msg = required('msg'),
  convention = ''
}) => {
 // ...
}