Option to require a comment under @file tag

[claudiu-cristea]

Motivation

With require-file-overview rule we're able to enforce a @file tag for each JS file. However, this could not be enough for some projects. I want to be able to enforce also a comment just after the @file tag:

/**
 * @file
 * Relevant description about what this file is doing.
 */

Current behavior

This doc block is valid:

/**
 * @file
 */

Desired behavior

I would like to have an option that enforces this:

/**
 * @file
 * Relevant description about what this file is doing.
 */

Alternatives considered

N/A

[brettz9]

Do you want to require that every file has a @file and a comment, or do you merely want to enforce that any @file be accompanied by text?

Btw, per https://jsdoc.app/tags-file.html (and general practice with JSDoc), the description follows the tag on the same line. Are you ok with ensuring any such description exists or do you only want one where begun by a newline?

[claudiu-cristea]

Do you want to require that every file has a @file and a comment, or do you merely want to enforce that any @file be accompanied by text?

I'm doing Drupal development and we have some rules also for JS files. In most of the projects we're following the Drupal core rules, including for JS. Here's the rule for the @file tag: https://www.drupal.org/docs/develop/standards/javascript/javascript-api-documentation-and-comment-standards#s-documenting-a-javascript-file

Btw, per jsdoc.app/tags-file.html (and general practice with JSDoc), the description follows the tag on the same line. Are you ok with ensuring any such description exists or do you only want one where begun by a newline?

It's common for files in Drupal to add the description on a new line, just after @file (for PHP but also for JS files). See the above link

[brettz9]

Do you want to require that every file has a @file and a comment, or do you merely want to enforce that any @file be accompanied by text?

I'm doing Drupal development and we have some rules also for JS files. In most of the projects we're following the Drupal core rules, including for JS. Here's the rule for the @file tag: https://www.drupal.org/docs/develop/standards/javascript/javascript-api-documentation-and-comment-standards#s-documenting-a-javascript-file

I'm still not clear by that re: my question. Every file must have one then?

Btw, per jsdoc.app/tags-file.html (and general practice with JSDoc), the description follows the tag on the same line. Are you ok with ensuring any such description exists or do you only want one where begun by a newline?

It's common for files in Drupal to add the description on a new line, just after @file (for PHP but also for JS files). See the above link

Ok, but do you care personally about enforcing a newline there or not?

[claudiu-cristea]

Every file must have one then?

Yes.

Ok, but do you care personally about enforcing a newline there or not?

Projects can do whatever they want (including not requiring @file). But as these are Drupal projects, yes, I care about having the comment on a new line as I want to align as much as I can with Drupal core rules.

Note that for @param, Drupal coding standards also requires the parameter description to be on the following line

[claudiu-cristea]

But I think it could be an option whether to show inline of after

[brettz9]

We could add a general option to this rule to enforce that some content is present, but I think to get your stated goals, you should instead use: jsdoc/no-missing-syntax (for @file) and jsdoc/no-restricted-syntax (for @param)

For @file, you can provide something like the following options object for jsdoc/no-missing-syntax:

        {
          contexts: [
            {
              comment: 'JsdocBlock:has(JsdocTag[tag=file][description=/^\\n/])',
              context: 'any',
              message: 'must have @file description with newline',
            },
          ],
        },

This should ensure (assuming you are using the latest release) that a @file with initial newline is present in every file.

For param, since you presumably might not need a @param present in every file, you can instead use jsdoc/no-restricted-syntax but with :not() to reverse the expectation, allowing the rule to complain if a param is present and found without an initial newline.

        {
          contexts: [
            {
              comment: 'JsdocBlock:has(JsdocTag[tag="param"]:not([description=/^\\n/]))',
              context: 'any',
              message: 'Ensure params have an initial newline in the description.',
            },
          ],
        },

(Alternatively, we could avoid the :not() and use a negated regex, but just demonstrating.)

[brettz9]

Since, as mentioned, you can use the jsdoc/no-missing-syntax and jsdoc/no-restricted-syntax to enforce the desired behavior for newlines, I'm going to close this issue. Feel free to comment further as needed.

[claudiu-cristea]

Thank you for support. Didn't had time to experiment but I will