Parameter name array syntax

[dhotson]

Hi,

I've started using apidocjs but noticed that it doesn't currently handle parameter names with [ ] brace characters in them.
Do you think it makes sense to support these kinds of parameter names in apidoc?

For example:

@apiParam {String} item[]
@apiParam {String} thing[name]
@apiParam {String} [something_optional[]]

[rottmann]

Thanks, have to think about it.
Currently the notation would look like this

@apiParam {String[]} item
@apiParam {Object}   thing
@apiParam {String}   thing.name
@apiParam {String[]} [something_optional]

[dhotson]

Ah cool thanks, that's interesting.

I guess the dot syntax is assuming API params are submitted in json format?

In my case, our API is using html form application/x-www-form-urlencoded style encoding so our param names have brace characters in them. Ideally our documentation would match that as closely as possible.

e.g. in curl a request would look something like this:

curl -XPOST -d 'item[]=aaa&item[]=bbb' https://api.example.org

[dhotson]

Hi @rottmann,

Any further thoughts on this? :)

It seems to be a common practice to use this array style format for param names in APIs that accept form encoded values.

This PR currently covers just two simple cases for this style. e.g. foo[] and foo[bar]
Eventually it might be good to allow for nested structures too. e.g. foo[bar][baz]

[rottmann]

Here is a little discussion about it apidoc/apidoc#267 and the different use cases the apiParams must fulfill.

[nettiopsu]

@rottmann, I strongly suggest to approve this already. This problem exists since April and the solution suggested by @dhotson perfectly works with all the cases described in apidoc/apidoc#267. Current apidoc-core just does not work at all with such parameters breaking parameters' HTML layouts in a documentation. This solution will just make it work with square brackets, it does not need to be even documented

[rottmann]

Thanks, added in 0.14.0