Pete Gonzalez

As far as the AST representation for headings, probably they should not be a nesting structure. They can be a regular section member similar to a `DocParagraph`.

> Let's start with 2 not 1, since the first line of docs is the headline 1 and in HTML only one `h1` is suggested/allowed. One `#` would be marked...

> If there is no nesting, should tsdoc really try to enforce/warn about which levels are used? Can it just not pass through the headers that are given? There are...

We discussed the `@see` and `@seealso` tags a few times before. I had trouble finding a spec for how they are supposed to be rendered by a documentation system. You...

I'm also interested to know more about JSDoc's semantics. [Their docs](https://jsdoc.app/tags-see.html) give this example: ```ts /** * @see {@link foo} for further information. * @see {@link http://github.com|GitHub} */ function bar()...

What happens if you have multiple `@see` tags?

Ahh ok. So `@see` is a block tag where each block becomes one item in a list of references. If our documentation template uses bullets, then our spec is that...

JSDoc also specifies: > You can provide either a symbol's namepath or free-form text. This aspect seems problematic. Namepaths are ambiguous with free-form text. For example, if instead of this:...

> In @hbergren's version of my `@see` PR I commented that it would be useful to support both with a warning on the `@see Elements` case to better support anyone...

Good point. I really want to go implement this for API Extractor. It's so little work. :-)