`require-param`

[thernstig]

Consider this code:

import { ReactNode } from 'react';

import styles from './hero-section.module.css';

interface HeroSectionProperties {
  /** Background image URL */
  src: string;
  /** Content to render centered within the hero */
  children: ReactNode;
  /** Additional CSS class names to merge */
  extraClasses?: string;
  /** Optional accessible label describing the background image */
  backgroundLabel?: string;
}

/**
 * Full-bleed hero section with background image.
 *
 * @returns JSX Element
 */
export function HeroSection({
  src,
  children,
  extraClasses,
  backgroundLabel,
}: HeroSectionProperties) {
  // Inline style for background image to keep CSS module generic
  const style = { backgroundImage: `url(${src})` } as const;

  return (
    <section
      className={[styles['hero-section'], extraClasses].filter(Boolean).join(' ')}
      style={style}
      aria-label={backgroundLabel}
    >
      <div className={styles.content}>{children}</div>
    </section>
  );
}

export default HeroSection;

Using jsdoc.configs['flat/recommended-typescript', which includes jsdoc/require-param, it warns about this:

Missing JSDoc @param "root0" declaration.eslint[jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header)
Missing JSDoc @param "root0.src" declaration.eslint[jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header)
Missing JSDoc @param "root0.children" declaration.eslint[jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header)
Missing JSDoc @param "root0.extraClasses" declaration.eslint[jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header)
Missing JSDoc @param "root0.backgroundLabel" declaration.eslint[jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header)

However, the best practice in modern code with TypeScript is to describe component properties directly using an interface or type for props, rather than relying on JSDoc @param comments for property descriptions.

Should jsdoc.configs['flat/recommended-typescript' prefer to NOT include jsdoc/require-param?

I did not want to open either a bug or feature request since I am not sure if this is even feasible.

[brettz9]

I think a rationale for @param is that they can be formally documented with extra descriptive text. The typescript config should already deter the (redundant) use of types.

[thernstig]

@brettz9 interface HeroSectionProperties already contains descriptive text for the params. Why would I want other/extra descriptive text on @param as well? It would override what I have in the interface (and thus editor completions) as they do not merge.

Or am I maybe missing the point?

[brettz9]

I see. My mistake. I am unaware of current best practices for TS, but I wonder how well documentation tools (in addition to VSC) process the interface descriptions as they have @params.

[thernstig]

I asked three AIs about this and they all said best practice is to keep the description on the interface/type in this scenario. As the @param is redundant and descriptions should be done on props inside the interface/type instead.

Just to be specific and add more context.

Here it how it looks in IntelliSense/auto-completion in editors that support it:

Hovering the function definition does however not show anything:

however in this last example, one can hover the interface name in the signature to see it's descriptions.

Should I amend this post with more examples i.e. how it looks somehow with @param included as well? Does it help taking a decision what is best?

[brettz9]

That would be informative, sure. Also, if you know about TS doc-generation whether they use that info.

And I think it would be helpful to have other TS folks chime in too if possible. @JoshuaKGoldberg : If I can bother you again, especially since you came up with the TS configs, what do you think of dropping this rule from the TS configs?

[JoshuaKGoldberg]

best practice in modern code with TypeScript is to describe component properties directly using an interface or type for props, rather than relying on JSDoc @param comments

I don't believe either way is preferred. They're both totally valid. Using an interface/type can add more conceptual and/or runtime bloat than many functions need. If a function has just one or two parameters, it's totally reasonable to use standard @param comments for them.

I asked three AIs about this and they all said

This is not convincing to me 🙂 AIs are wrong all the time. If they can provide primary sources then I'd want to read them. But I don't trust anything an AI says on its own.

what do you think of dropping this rule from the TS configs?

I personally don't use this rule because I find it annoying to always require params 😄. I find that it often intersects with the intent of jsdoc/informative-docs. Instead, I just enable the contents-typescript, logical-typescript, and requirements-typescript configs.

What is the intent of recommended-typescript? Is it that every entity has at least some description? If so, I would lean towards changing the default of jsdoc/require-param to only report if the entity doesn't have a TypeScript type declared. As in, this would be fine:

/** (nothing) */
function greet(text: string) { /* ... */ }

...but this would be a rule report:

/** (nothing) */
function greet(text) { /* ... */ }

[brettz9]

Thank you very much for your thoughts on this, @JoshuaKGoldberg .

what do you think of dropping this rule from the TS configs?

I personally don't use this rule because I find it annoying to always require params 😄. I find that it often intersects with the intent of jsdoc/informative-docs. Instead, I just enable the contents-typescript, logical-typescript, and requirements-typescript configs.

It appears the requirements-typescript config includes require-param, but I guess you are disabling it then?

What is the intent of recommended-typescript?

These are just the general recommended rules of the project.

Is it that every entity has at least some description?

Since the requiring of param types is excluded, I think yes, the relevance is getting a description.

If so, I would lean towards changing the default of jsdoc/require-param to only report if the entity doesn't have a TypeScript type declared. As in, this would be fine:

/** (nothing) /
function greet(text: string) { / ... */ }

...but this would be a rule report:

/** (nothing) /
function greet(text) { / ... */ }

I'm not sure that this would help because if one wanted a description, one still would presumably not get it with inline types. But I guess per @thernstig 's discussion, if a type was given for the whole function, perhaps it would be more likely that documentation should or could exist on that interface, and there'd thus be no need for @param docs. Perhaps we could do this with an option set by default in the typescript configs to true so one wouldn't even need to disable the rule.

[thernstig]

Reading your discussions, I think disabling jsdoc/require-param in TypeScript configs is the proper solution. One can always enable it again, but I recon most do not want it. @brettz9 unsure what you mean with the option and setting it to true but if it achieves the same thing then all good.

This is an aside:

This is not convincing to me 🙂 AIs are wrong all the time. If they can provide primary sources then I'd want to read them. But I don't trust anything an AI says on its own.

I agree, one should know the shortcomings if using an AI and have experience with it. But Perplexity is rather good at compiling actual sources, and asking the question objectively without any pro/cons against/for gave that answer. So I also do not agree if one understands to use it sensibly. Try yourself and then you can question the sources since you are obviously the TypeScript guru out of the two of us 😄

[thernstig]

@brettz9 thanks to that @JoshuaKGoldberg chimed in with some sound advice, I had to go back and check myself for what I had asked and checked around.

My scenario was more so about React specifically, where one sometimes defines props and their descriptions in an interface. But for a function signature in general it makes sense using @param and enforce it in TypeScript, since you need the description of the params somewhere.

So I am backtracking on this issue 😆

I suppose there is no way to check if an Interface is used that already has descriptions, and only then not enforce @param? That would be the ideal solution.

[brettz9]

I suppose there is no way to check if an Interface is used that already has descriptions, and only then not enforce @param? That would be the ideal solution.

Yes, the option I was speaking about was to simply check if there was a type for the function itself, and if so, assume it points to an interface with descriptions and thus avoid need for documentation of params.

[thernstig]

@brettz9 got it. I am now not sure that is the most common scenario even in the React case. As we see in #1511 (comment) there is no description of the the properties immediately in the popup. Unsure how it works in other editors such as vim or emacs etc.

So maybe even most users prefer to have the @param descriptions even if using an Interface, omitting the descriptions from the Interface.

The most robust solution would be to require @param if the Interface itself had no description for props, but that sounds impossible?

[brettz9]

The most robust solution would be to require @param if the Interface itself had no description for props, but that sounds impossible?

It'd require that the interface be defined within the file, and even then, it'd be cumbersome to get at the comments.