feat: @since tag

[Bugs5382]

Search Terms

Encountered an unknown block tag

So maybe I am wrong, but I had @since in my comments, and Typedoc format this correctly as "Since" with the version, yet now it's reporting that @since is not a valid tag. Either it's a bug or, I guess, a new feature. I didn't know where to go in terms of the report... logged a feature request. I looked in the code and could not find anything.

Problem

44:5 - [warning] Encountered an unknown block tag @since

44       * @since 1.0.0

Suggested Solution

Add it as a valid tag since it seems to be outputting just fine:

[dbrugger]

seeing same warning with @file in latest version

[Gerrit0]

With 0.26, TypeDoc now warns if a tag isn't recognized when being parsed:

TypeDoc will now warn if a block tag is used which is not defined by the --blockTags option.
0.26.0 changelog

This was added to make usage of tags which are effectively ignored by TypeDoc visible. TypeDoc will recognize block tags with context clues, so even something like:

/**
 * @nobodyKnowsWhyThisIsATag Some text
 */

will be parsed, probably "correctly" as intended by the author, despite not being recognized by TypeDoc.

JSDoc defines 85 block tags, most of which have no effect on the documentation coming out of TypeDoc. For tags where there is no expected behavior beyond just rendering the tag, and are reasonably widely used, like @author, and @since, I'm mainly just waiting for feature requests to add them to the default list. (I actually thought I'd included @since when I did a first pass through the JSDoc tags)

For other tags like @file, where JSDoc attaches a behavior to the tag which is not respected by TypeDoc, I do not plan on adding them to the default tag list. TypeDoc's equivalent of @file is @packageDocumentation or @module

---

If you have tags in your comments which are not part of the default suite, you can tell TypeDoc about them with the blockTags option or through a tsdoc.json.

[Bugs5382]

@Gerrit0 Thanks! I thought I was going crazy. Thanks for adding this in to the main code base 👍

[handerss-spotfire]

What is the syntax when providing --blockTags as a CLI argument? I get the following error no matter what I try:

blockTags must be an array of valid tag names

[Gerrit0]

I don't recommend setting that option from the command line, as setting it overrides TypeDoc's default set of tags, so you'll have to provide every single tag you use...

$ typedoc --blockTags @since --blockTags @param --blockTags @remarks