Fix issue #1497; JSDoc params in the multiline comment example

[pratyushtewari]

Added the missing @params which confuses the developers that it is bad to use these tags

Fixes #1497

[ljharb]

I think you may have misunderstood me - it IS bad to use jsdoc. Do not use it.

The purpose of this example isn't about jsdoc; but I want it conveyed that JSDoc is used, and I don't want to convey that JSDoc is acceptable.

[tkharuk]

Any reference or discussion to why JSDoc-style comments are "bad"?

[ljharb]

Not that I know of, but comments should never describe "what" the code is doing; only "why" and history/motivation. If code needs a comment to explain what it's doing, the code isn't clear enough - and if documentation for an API is laborious to write by hand, the API is too complex.

[tkharuk]

Does JSDOC-style imply 'what' over 'why'?
The body of the comment can be anything.
Or do You mean that by mentioning @params alone is enough for it is being 'what'?

[ljharb]

Yes - JSDoc describes what params a function takes, and usually their type - and also what type of value is returned. The descriptions can be used to explain "why", but no special format is needed for that.

[tkharuk]

Well, for me that has been always more of a handy snippet for writing comments...
Thanks, got the idea and motivation behind this!

[pratyushtewari]

Well, we use JSDoc to create our documentation website and not to read the code. I am sure there are a lot of other people/companies that are using them as well. So if not JSDoc then do you have any suggestions on other good documentation libraries that is as easy as this one?

[ljharb]

My perspective is that if documentation is too hard to hand-write, then the API its documenting is too complex.

[pratyushtewari]

I need to provide a website of documentation without giving the whole code base to everyone. I'll decline the pull request but I have to disagree that there is no need to give documentation for your product.

[ljharb]

Sorry if I wasn't clear; I think documentation is essential! However, I think that that documentation should be manually hand-written by a human, not generated by a tool.