[FEAT]: Make "Oneline JSDoc Comments" rule as optional

[franquil]

[FEAT]: Make "Oneline JSDoc Comments" rule as optional

[HoukasaurusRex]

Easily noticeable parameters' types to avoid unnecessary errors at coding;

The JSDoc rule applies to exported symbols. There's an alternative solution to providing param intellisense suggested by @TNieminen here

Documentable detailed information about the objects/functions that commented, which can be beneficial for new developer to get to know those items; (For example, the generated Swagger API doc provides a huge assistance to developers that need to get to know the APIs, with functions/utils document which can be generated via JSDoc, it may provide similar benefits as well.)

We used to have something like this, but the jsdoc documentation cli was frequently broken by certain comments we used for typings intellisense, so when having to choose between jsdoc generated docs and code editor intelliese, we decided to stop supporting jsdoc documentation generation. It hasn't been missed, and I believe we've had it for awhile even with you on our team, so the fact no one remembers it is telling.

Richer IntelliSense that developers could interact with;

See responses above

Better understandable code, even developers without extra IntelliSense feature, they could easily unstandand the code;

This is subjective how much jsdoc helps a dev understand a function. Anecdotally, I often skip the jsdoc in favor of intellisense, function name, description, and worst case, reading the function definition. Onelining jsdoc comments, and perhaps even param defaulting as suggesting in PR #6 , and better function naming should be the prerogative of code style, not obsessive @param, @returns, @description doccing. Adding comment complexity increases code complexity.

Rising awareness of the types being used to reduce potential issues (especially for weak-typed programming languages like js);

Again, this in my opinion is much more intuitive in #6 than @params declarations

However, there're drawbacks, for example, it may increase the complicity of managing comments, expand developing time, making the comments a bit verbose sometimes, etc.

Yes, in fact again anecdotally, I've frequently had to choose between having acceptable documentation by spending hours trying to update/debug/understand jsdoc param declarations or having undocumented (or incorrectly documented) code pushed immediately.

You can see more about the motivations behind this decision in Deno's styleguide

[TNieminen]

@franquil @HoukasaurusRex If I understand correctly the main concern was that we would not have type feedback with the single-line comments, which is answered with this merged pr that outlines using default variables.

I propose if no further comments this issue to be closed.

[HoukasaurusRex]

Closing due to staleness

[franquil]

Sorry for the late comments.

jsdoc documentation cli was frequently broken by certain comments we used for typings intellisense, so when having to choose between jsdoc generated docs and code editor intelliese, we decided to stop supporting jsdoc documentation generation.

Could you show examples in what circumstances that the comments break the typings intellisense? What the reasons for that? I suppose jsdoc is not opposite of code editor intelliese, it would increase the experiences of coding, and that's why it's popular among many js based projects and developers.

It hasn't been missed, and I believe we've had it for awhile even with you on our team, so the fact no one remembers it is telling.

The reason for that may be because people didn't take it seriously, and people may forgot to update it. That's the problems need to solve, because if jsdoc is useful, people should care about it, instead of abandoning it. And there're quite a few benefits it would brings, no need to mention here.

I often skip the jsdoc in favor of intellisense, function name, description, and worst case, reading the function definition.

There're varied advantageous that the jsdoc could bring, if it's done well, developers shouldn't need to read inside of the function. The doc should be enough for them to interact with the doced functions. I suppose that would save people's time rather than wasting time to understand it.

Onelining jsdoc comments, and perhaps even param defaulting as suggesting in PR #6 , and better function naming should be the prerogative of code style, not obsessive @param, @returns, @description doccing.

I agree that 'better function name' does make the code easier to understand, however, that may belong to another topic. In terms of the docs/comments, if functions are simple, I suppose oneline js comment should be sufficient. Considering the growing complexity of functions, in some cases, which suppose to not very easy or need more time for people to know. That could solved by proving detail jsdoc, so they don't need to know how the function does the job, they can use it by reading the doc.

Adding comment complexity increases code complexity.

I reckon it would increase the time for commenting the function/code, not sure what 'code complexity' in this case indicate? The aim of it is supposed to assist developers to easily understand the complicated code.

I've frequently had to choose between having acceptable documentation by spending hours trying to update/debug/understand jsdoc param declarations or having undocumented (or incorrectly documented) code pushed

That may caused by inappropriately jsdoc writing/maintaining? That's not the problems of jsdoc I suppose, that's the problems that people who writing the code, and failed to updating jsdoc because of improper pratice?

The deno stylecode(https://deno.land/manual/contributing/style_guide#use-jsdoc-for-exported-symbols) that frequently mentioned, it looks like a company's own styleguide. It seems to not target to serve as a comprehensive Javascript coding styleguide. The styleguide seems to be a small chapter in the whole library guide. I didn't see the popularity, authority of it, and not sure whether it's appropriate to apply. And I see the company mentioned a lot Typescript in the guide, not sure it's supposed to apply in Typescript, or in plain Javascript.

My intention is not opposing the oneline comment rule especially for simple functions which oneline is sufficient to describe them. Nevertheless, for complicated function that oneline is not enough, more information that according the certain standards (jsdoc in this case) would be beneficial for following developers to interact with the code without spending too much time to understand it. Additionally, more benefits could be brought which no need to mention again, under that sacrifices of maintianing it.

And the propose is not about abonding oneline comment or jsdoc standard complied multiline comments, it's about making the 'oneline JSDoc comments' rule as optional for the sake of complicated functions that which oneline comment is not sufficient for the purpose, or people would prefer to provide more info about the function in order to let others know what it does.

@HoukasaurusRex @TNieminen

[HoukasaurusRex]

Could you show examples in what circumstances that the comments break the typings intellisense?

I don't have the time. Run the jsdoc cli against our codebase and you'll likely find out. You were working with us at the time we were using JSDoc to generate documentation. You never used it. You were working with us when we stopped using it because of these issues. You haven't missed it.

The reason for that may be because people didn't take it seriously, and people may forgot to update it.

See above.

There're varied advantageous that the jsdoc could bring, if it's done well, developers shouldn't need to read inside of the function.

Again, we want to take advantage of intellisense, not useless params declarations. Taking advantage of *intellisense would achieve what you want, which is what we're doing.

That may caused by inappropriately jsdoc writing/maintaining?

Also related to above comment. JSDoc Cli is at odds with VSCode JS/TS intellisense.

it looks like a company's own styleguide.

Deno is the JS runtime engine created by the same creator of Node.js as its spiritual successor, not just some company. It's used as an example for code style inspiration, not law. It's a huge project gaining a ton of traction in relation to all other new frameworks/languages and includes hundreds of contributors, so I'd say it's definitely an authority on JS code style.

I can see you feel very passionately about being able to have an exception to this rule, but your desires are also quite unclear. You say you're not arguing against the oneline JSDoc rule, however I haven't seen you actually give any reasoning towards anything else other than the nebulous "some situations". Could you provide an example then of what scenario you've faced where you need multiple lines to comment the exported symbol? Perhaps that would be an easier point to argue and save us both some time.