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

require specific tags #936

Closed
aureq opened this issue Dec 2, 2022 · 7 comments
Closed

require specific tags #936

aureq opened this issue Dec 2, 2022 · 7 comments

Comments

@aureq
Copy link

aureq commented Dec 2, 2022

Motivation

I'm writing some code and part of this, I would like to enforce a rule/check that would require developers to put a specific (custom) tag in the jsdoc.

The rational is JSdocs are really helpful to improving code quality, but if this plugin could enforce the presence or any tag (custom and existing ones), it would allow developers extend the scope of their documentation greatly.

/**
 * This is a description for my variable
 *
 * @link https://interna-link.example.com/docs/dev/ (or any url really)
 */
const export myVariable: string = "hello JSDoc fans";

Maybe a generic require-tagname would be the way to go? Like it is done for require-property but with no checks on value.

Current behavior

  • I have been able to correctly declare my custom tag (@link) but I'm struggling find a way to enforce its presence in each jsdoc section across the code base.

Desired behavior

  • With the new rule, a warning or an error could be triggered to indicate a specific @tag is missing from the JSDoc section.
  • What would be awesome, would be the ability to trigger the rule baaed on the context (variables, classes, properties...) but that's beyond what I would like to have right now.

Alternatives considered

  • I haven't found any so far I'm afraid. But maybe I didn't look at the right place.

Thank you for considering this feature request.

@brettz9
Copy link
Collaborator

brettz9 commented Dec 5, 2022

See jsdoc/no-missing-syntax which should allow you to do what you are seeking, including specifying precise contexts.

If you are using a custom tag, the rule jsdoc/check-tag-names should also be of interest along with the setting, settings.jsdoc.structuredTags. However, I would recommend probably just using the existing standard tag, @see, given that it can be used for linking, at least if you use the form, @see {@link https://...}. See https://jsdoc.app/tags-see.html .

We don't have rules to specifically enforce inline tags like @link, but to enforce that there is always a @see, you could do something like:

'jsdoc/no-missing-syntax': ['error', {
  {
    comment: 'JsdocBlock:has(JsdocTag[tag="see"])',
    context: 'any',
    message: '@see required on each block',
  }
}]

...and you should also be able to use jsdoc/match-description to enforce that @see begins with {@link and ends with }.

Closing as this should resolve the issue, though feel free to report further issues if you run into trouble.

@Narretz
Copy link

Narretz commented Dec 9, 2022

Hi @brettz9, I've tried your code snippet:

    'jsdoc/no-missing-syntax': [
      'error',
      {
        contexts: [
          {
            comment: 'JsdocBlock:has(JsdocTag[tag=see])',
            context: 'any',
            message: '@see required on each block',
          },
        ],
      },
    ]

but it doesn't work for me. However, you gave a different code snippet in another issue: #876

    'jsdoc/no-restricted-syntax': [
      'error',
      {
        contexts: [
          {
            comment: 'JsdocBlock:not(*:has(JsdocTag[tag=see]))',
            context: 'any',
            message: '@see required on each block',
          },
        ],
      },
    ]

Why does the second work, but the first doesn't?

And wouldn't it make sense to add this to the docs, since it seems like a common use case?

@brettz9
Copy link
Collaborator

brettz9 commented Dec 9, 2022

Hi @brettz9, I've tried your code snippet:

    'jsdoc/no-missing-syntax': [
      'error',
      {
        contexts: [
          {
            comment: 'JsdocBlock:has(JsdocTag[tag=see])',
            context: 'any',
            message: '@see required on each block',
          },
        ],
      },
    ]

but it doesn't work for me. However, you gave a different code snippet in another issue: #876

    'jsdoc/no-restricted-syntax': [
      'error',
      {
        contexts: [
          {
            comment: 'JsdocBlock:not(*:has(JsdocTag[tag=see]))',
            context: 'any',
            message: '@see required on each block',
          },
        ],
      },
    ]

Why does the second work, but the first doesn't?

Ah ok, yes, the second one is probably what you want.

The second one will complain if there are JSDoc blocks which don't have a @see.

The first should complain if your document doesn't have at least one JSDoc block with a @see; it doesn't check each block but it does insist that at least one exists in each document. The second one allows for no JSDoc blocks while the first does not, but if a JSDoc block insists, the second one will insist there is a @see.

And wouldn't it make sense to add this to the docs, since it seems like a common use case?

Our docs are getting too large as it is, and I'm not sure how common this use case is; it sounds to me like a lot of work, but happy if it works for ya. We do have other similar ones, though, in any case.

brettz9 added a commit to brettz9/eslint-plugin-jsdoc that referenced this issue Dec 9, 2022
@brettz9
Copy link
Collaborator

brettz9 commented Dec 9, 2022

On second thought, I guess we don't have quite this sort of use case in this rule, so I've gone ahead and added it to the docs. Thanks!

@Narretz
Copy link

Narretz commented Dec 9, 2022

Thanks @brettz9!

@aureq
Copy link
Author

aureq commented Dec 10, 2022

Thank you to both of you. @Narretz you solution works really well. Setting a context makes the solution even more flexible which is what I was looking for.

@github-actions
Copy link

🎉 This issue has been resolved in version 39.6.5 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants