Update jsdoc/check-tag-names to allow @property JSDoc tag

[Mrtenz]

jsdoc/check-tag-names by default does not allow @property in a typed system (such as TypeScript). This makes sense in places where it's possible to document a property directly, for example:

type SomeObject = {
  /**
   * Documentation for the property here.
   */
  someProperty: string;
};

This is not always the case however, especially when inferring types from structs for example, in which case we use something like this:

const SomeObjectStruct = object({
  someProperty: string(),
});

/**
 * Some object.
 *
 * @property someProperty - Documentation for the property here.
 */
type SomeObject = Infer<typeof SomeObjectStruct>;

For this reason I've updated jsdoc/check-tag-names to allow @property in TypeScript as well.

[Gudahtt]

Hmm. In a TypeScript context though, we'd be using TSDoc for documenting code, and TypeDoc for generating docs from those inline docs. Do either of those tools support @property? I was under the impression they did not.

Certainly declaring @property inline is useful for anyone reading the code directly, but it would be a shame to encourage a pattern of documenting properties that renders them invisible from intellisense popups/IDE autocomplete/generated docs.

[Mrtenz]

Hmm. In a TypeScript context though, we'd be using TSDoc for documenting code, and TypeDoc for generating docs from those inline docs. Do either of those tools support @property? I was under the impression they did not.

Certainly declaring @property inline is useful for anyone reading the code directly, but it would be a shame to encourage a pattern of documenting properties that renders them invisible from intellisense popups/IDE autocomplete/generated docs.

I just tested this with TypeDoc using this type:

/**
 * This is the main documentation for the `Foo` type.
 *
 * @property bar - This is the `bar` property.
 * @property baz - This is the `baz` property.
 */
export type Foo = {
  bar: string;
  baz: number;
};

Which renders as:

So it shows the documentation, but doesn't link them to the actual properties. In my IDE, @property does show up however. That's a shame 😕 I don't think there's a good alternative for @property in the case of documenting structs, since this doesn't show up at all:

const SomeObjectStruct = object({
  /**
   * Some documentation.
   */
  someProperty: string(),
});

[Gudahtt]

That's unfortunate. Maybe we can disable this rule in projects/directories/files that use superstruct? It seems like the rule is helpful outside of this one case. Certainly for superstruct, @property is better than nothing, even if it doesn't get picked up by intellisense.