Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: fix / clean up jsdoc comments #1342

Open
Zatan16 opened this issue Jul 28, 2023 · 14 comments
Open

chore: fix / clean up jsdoc comments #1342

Zatan16 opened this issue Jul 28, 2023 · 14 comments
Labels
chore General improvement code quality Code quality improvement documentation PR that adds or fixes docs; issue that points out issues with the docs

Comments

@Zatan16
Copy link

Zatan16 commented Jul 28, 2023

Motivation

Many people who use libraries not only use help of jsdoc for methods, but also for the parameters. So, moving the jsdoc declaration from before class to before constructor would definitely help many beginners using this library. Then, the descriptions would show up for the parameters as well.

Examples

No response

Possible workarounds

The possible workaround is that instead of moving the jsdoc completely to before constructor, the description can stay before class but the @param needs to be moved to before constructor

Additional information

You don't need to use tags such as @class and @constructor with ES 2015 classes—JSDoc automatically identifies classes and their constructors simply by parsing your code.

as stated by the documentation for classes

@appgurueu
Copy link
Collaborator

Documentation of constructor parameters of course needs to go with the constructor. Feel free to fix this. But a general description of the class should stick with the class and not be moved to the constructor.

@Zatan16
Copy link
Author

Zatan16 commented Jul 28, 2023

But when we keep the description to the constructor, it appears for the main class as well. That's how classes work with jsdoc. So you mean I need to go through all the files and fix it 😅. It's not that I don't want to do it but it's gonna take a lot of grind.

@appgurueu
Copy link
Collaborator

appgurueu commented Jul 28, 2023

But when we keep the description to the constructor, it appears for the main class as well

I'm not sure what you mean by this. In the documentation you linked, the example is

/** Class representing a point. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) { ... }
    ...
}

So clearly the description - in this case "Class representing a point" - should stick with the class rather than being moved to the constructor.

So you mean I need to go through all the files and fix it

You don't need to fix it, but you may fix it. You could consider automatizing this with some RegEx; use whatever you are most comfortable with.

It's not that I don't want to do it but it's gonna take a lot of grind.

It's fine, you don't have to fix it by any means. There are more interesting problems to solve than to fix this :)

@appgurueu appgurueu added code quality Code quality improvement documentation PR that adds or fixes docs; issue that points out issues with the docs chore General improvement labels Jul 28, 2023
@Zatan16
Copy link
Author

Zatan16 commented Jul 29, 2023

I'm sorry, I messed up a little. I came here as soon as I realized I messed up and saw your reply. I'm currently working on adding more shapes to the Geometry folder (like the square, rectangle, triangle, cube, etc.)

@Zatan16
Copy link
Author

Zatan16 commented Jul 29, 2023

Also, are there proper guidelines to write the code in? For example, use this and that for jsdoc, or use x spaces or x tabsize for indentation, etc.

@appgurueu
Copy link
Collaborator

Also, are there proper guidelines to write the code in? For example, use this and that for jsdoc, or use x spaces or x tabsize for indentation, etc.

See our contribution guidelines. We use StandardJS style, so 2 spaces for indentation. As for JSDoc: Just refer to their docs for best practice.

@Zatan16
Copy link
Author

Zatan16 commented Aug 7, 2023

I just realized, nowhere in the CONTRIBUTING.md does it say that I don't have to use the ; to end the sentence, so am I allowed to use it? I've seen all files do not use them, I might have missed checking a few.

@appgurueu
Copy link
Collaborator

appgurueu commented Aug 7, 2023

I just realized, nowhere in the CONTRIBUTING.md does it say that I don't have to use the ; to end the sentence, so am I allowed to use it? I've seen all files do not use them, I might have missed checking a few.

I'm not sure what you mean by this. If you mean using semicolons to delimit statements rather than relying on automatic semicolon insertion, please avoid this to comply with StandardJS style. Of course you have to keep using them in for-loops or the like though.

If you're referring to usage of ; as english punctuation: That is allowed within comments. If you do use it, note that it does not end, but rather separate sentences; it is effectively a compromise between a comma (,) and a colon (:). See e.g. Collins Dictionary for how to use semicolons in English.

@Zatan16
Copy link
Author

Zatan16 commented Aug 7, 2023

By sentence, i meant a code line. Thanks for clarifying

@ManvendraPSdev
Copy link

ManvendraPSdev commented Oct 4, 2023

@appgurueu please you assign this issue to me

@Bajpai25
Copy link

Bajpai25 commented Oct 4, 2023

@appgurueu
Please assign this issue to me.

@appgurueu appgurueu changed the title [FEATURE]: jsdoc not working properly when hovering over paremeters chore: fix / clean up jsdoc comments Oct 4, 2023
@mohmmadAyesh
Copy link

@appgurueu is this issue still open I want to contribute on cleaning up doc string?

@appgurueu
Copy link
Collaborator

appgurueu commented Mar 26, 2024

@mohmmadAyesh sure, feel free to work on it. (Please don't add redundant comments, though.)

@m3tal10
Copy link

m3tal10 commented Oct 10, 2024

Hey is this still issue available?
I am a beginner, I would love to work on this and I'd also need some guidelines to start my first contribution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
chore General improvement code quality Code quality improvement documentation PR that adds or fixes docs; issue that points out issues with the docs
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants