Enhance js doc

[fschmenger]

This PR extends the JSDoc to use the bracket syntax for optional parameters, e.g.
@param {string} [p3] - Another optional param (JSDoc syntax)
It also fixes some minor documentations issues, like unused parameters or documenting on no longer existent parameters.

[fschmenger]

A lot of functions and components are not properly documented. I added nothing within this PR so far, but we should make a note to extend JSDocs where missing.

[sronveaux]

Hi @fschmenger,

Thanks for this one!

I reviewed what you did here but must admit I didn't parse the whole codebase to ensure all the optional parameters are now correctly documented... for what I saw, it is correct and is already way better like this, not to say that the changes you made makes the whole thing more readable too!

I only added some suggestions, all in the same file and for the same topic, concerning documenting parameters with properties... feel free to include them here of later as you wish!

As stated in your comment, JSDoc comments would deserve to be addressed where missing and I think they also should be uniformized from file to file. Some have spaces between description and @tags while some don't, descriptions sometimes start with an uppercase and sometimes not, descriptions sometimes finish with a fullstop sometimes not, etc... this is purely stylistic and perhaps not that important but sticking to the same rules everywhere makes it more readable IMHO.
The standard doesn't discuss some of these points and even some style guides like the one of Google don't talk about these neither.
Perhaps a simple way to start would be to install a plugin like eslint-plugin-jsdoc and include the jsdoc/recommended rules to see where it leads... I don't know what you think about it, perhaps you can open an issue with your own thinkings about this one?

Talking about issues, this PR fixes #448 I opened some weeks ago. This one can be closed when this will be merged!

Apart from the few suggestions which I let you choose whether to include them here or not, I approved the PR which is a very nice enhancement to current codebase!
Feel free to merge at will!

[fschmenger]

Hi @sronveaux,

good catch on commenting properties of an object parameter, I added those as suggested.
According to the JSDoc Cheatsheet it should be @param {number} with a lowercase number. However - as we have those all over the code - I will open up an issue as you suggested and keep track of this among the aforementioned things.

Thanks for the review and the comments, I will merge now.