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

Implement eslint-plugin-jsdoc (only for loopback monorepo) #5375

Closed
wants to merge 1 commit into from
Closed

Implement eslint-plugin-jsdoc (only for loopback monorepo) #5375

wants to merge 1 commit into from

Conversation

frbuceta
Copy link
Contributor

@frbuceta frbuceta commented May 9, 2020

Today I changed editor and I have noticed that the JSDoc are not good in some cases. So I want you to think what you think of this.

It is only for the monorepo, not for the general configuration @strongloop/loopback-maintainers

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

  • npm test passes on your machine
  • New tests added or existing tests modified to cover all changes
  • Code conforms with the style guide
  • API Documentation in code was updated
  • Documentation in /docs/site was updated
  • Affected artifact templates in packages/cli were updated
  • Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

@frbuceta frbuceta marked this pull request as draft May 9, 2020 18:07
@dougal83
Copy link
Contributor

dougal83 commented May 9, 2020

Hey @frbuceta , please excuse my ignorance in this area but what does this add to the project? Is it different to tsdocs? As I understand it, the tool picks up comments in code and compiles web pages essentially containing the comments.

@frbuceta
Copy link
Contributor Author

frbuceta commented May 9, 2020

Hey @frbuceta , please excuse my ignorance in this area but what does this add to the project? Is it different to tsdocs? As I understand it, the tool picks up comments in code and compiles web pages essentially containing the comments.

This checks that you write JSDocs correctly. Now you can see here that many are not well ... that's why the tests fail

@raymondfeng
Copy link
Contributor

@frbuceta I suggest that we add the jsdoc rule to a separate file and have the main .eslintrc.js to extend from it and the TS one. It might only be useful for *.js files.

The jsdoc rule does not apply to most TS files. For example, the tsdoc can infer param and return types. Tsdoc discourages to specify types in comments for such elements. For example,

/**
 * @param x - X
 * @param y - Y
 */
function (x: string, y: number) {
}

It's perfectly fine for tsdcos, but jsdoc plugin complains that x and y are missing types.

@bajtos
Copy link
Member

bajtos commented May 14, 2020

@frbuceta I suggest that we add the jsdoc rule to a separate file and have the main .eslintrc.js to extend from it and the TS one. It might only be useful for *.js files.

The jsdoc rule does not apply to most TS files. For example, the tsdoc can infer param and return types. Tsdoc discourages to specify types in comments for such elements. For example,

/**
 * @param x - X
 * @param y - Y
 */
function (x: string, y: number) {
}

It's perfectly fine for tsdcos, but jsdoc plugin complains that x and y are missing types.

Recently, API Extractor was enhanced (fixed?) to recognize even shorter syntax:

/**
  * @param x Description of param x
  * @param y Description of param y
  */
 function (x: string, y: number) {
 }

See microsoft/tsdoc#206. (Other related discussions: #2933, microsoft/tsdoc#128.)

Can we use eslint-plugin-tsdoc to validate our tsdoc comments? This plugin is officially recommented by tsdoc (see here). tsdoc is powering api-extractor that we are using to build our api docs.

@bajtos
Copy link
Member

bajtos commented May 14, 2020

@frbuceta I love the idea of linting our tsdoc comments ❤️ I am never sure if I am writing those comments correctly and most of the time I am too lazy to check how they are rendered in our API docs, so having an automated linter would be great 👏

@raymondfeng
Copy link
Contributor

Recently, API Extractor was enhanced (fixed?) to recognize even shorter syntax:

Yes, I realized that. I would say it's a fix :-).

@frbuceta
Copy link
Contributor Author

I close this? @raymondfeng is doing it in another PR

@frbuceta
Copy link
Contributor Author

@frbuceta I love the idea of linting our tsdoc comments ❤️ I am never sure if I am writing those comments correctly and most of the time I am too lazy to check how they are rendered in our API docs, so having an automated linter would be great 👏

I love that you like it

@bajtos
Copy link
Member

bajtos commented May 15, 2020

I close this? @raymondfeng is doing it in another PR

I think that would be best. You can always reopen this PR in the future in case #5435 goes nowhere.

@bajtos bajtos closed this May 15, 2020
@frbuceta frbuceta deleted the eslint-plugin-jsdoc branch May 15, 2020 13:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants