[WIP] Improve the output @param tags

[jackcannon]

Originally part of https://github.com/futurGH/ts-to-jsdoc/pull/22 , with additional changes

• Support for optional params (both param?, and param = x), wrapping the output name in square brackets
• Include default values for params where applicable
• Always remove and re-add @param and @return tags, so that they are always in the correct order
• Support correct JSDoc syntax for rest parameters

Note: this conflicts with https://github.com/futurGH/ts-to-jsdoc/pull/24 which should be merged first, and this PR rebased and updated

[futurGH]

My only worry with adding the dash between name and comment is that it might constitute a breaking change for users feeding ts-to-jsdoc's output into a tool that has worked fine with the current format (which is the format used by the Closure Compiler). On the other hand, TSDoc does specify it, and the JSDoc tool, while not formally specified, does assume its existence. One option would be to split this off into its own major version bump? It does seem wasteful for something that is technically a fix, though.

[jackcannon]

Yeah, that's a fair point. I can remove the explicit dash handling. The only source of the description/comment is if one is already there in the JSDoc, so we can just use it as is (dont add a dash if missing, dont remove one if present).

Would that work?

[futurGH]

That would be great! It's something I should probably make a decision on at some point, but I don't want it to block these changes.

[jackcannon]

Done. I also added a corresponding test to the tests PR: https://github.com/futurGH/ts-to-jsdoc/pull/27/commits/83d0c501289804771c45b69a857fb02bbfbd2144

[futurGH]

Much appreciated!