microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.7k stars 130 forks source link

Configuration option to parse out all unescaped unknown @<tag> blocks #293

Open jasonkuhrt opened 3 years ago

jasonkuhrt commented 3 years ago

Currently something like this:

  /**
   * foo summary
   * 
   * @custom foo
   */
  export interface B {}

Leads to parsing @custom foo as part of the summary text.

Could there be a mode to treat any line-starting unescaped @<valid_tag_name> as an unknown tag block? It would parse as simply:

  1. the name of the unknown tag
  2. the content of the tag (first line and following lines until end or next tag)

A use-case for this would be a doc tool listing the unknown tags with relative niceness, e.g.

##### Unknown Tag 1

<content>

##### Unknown Tag 2

<content>
octogonz commented 3 years ago

🤔 Given that most TSDoc tags are block tags, maybe by default @custom should be interpreted as a block tag.

jasonkuhrt commented 3 years ago

No objections. What would the alternatives be?