Tsdoc: Where are TSDoc syntax specifications?

[qortex]

I can't seem to find a simple documentation on the TSDoc syntax. Where is it located?

Closest I could find is: https://github.com/Microsoft/web-build-tools/wiki/API-Extractor-~-AEDoc-tags

[octogonz]

From the README.md:

Where are we on the roadmap?

Already completed:

• Write up all the interesting design questions as "RFC" GitHub issues to collect community feedback
• Arrive at an initial consensus on the basic approach and strategy for TSDoc
• Develop an initial feature-complete prototype of the @microsoft/tsdoc library and publish the NPM package
• Convert Microsoft's API Extractor tool to use @microsoft/tsdoc (replacing its proprietary AEDoc engine); this demonstrates that TSDoc can meet the needs of a large production documentation web site

What's next:

• Write up an initial draft of the TSDoc spec document, which outlines the proposed standard
• Collect community feedback and integrate it into the draft, then publish the first "official" 1.0 spec
• Review the @microsoft/tsdoc API with various integrators, including TypeScript and VS Code
• Publish the first "1.0.0" stable release of the @microsoft/tsdoc package
• Help onboard various partners

[octogonz]

We should have the first draft sometime soon. I've been busy wrapping up API Extractor 7, which implements the new declaration reference syntax (see DeclarationReferences.ts). This aspect of TSDoc went through several iterations of design discussion, so I wanted to have a working proof-of-concept before we write up the spec.

[qortex]

Great, thanks for the awesome achievements!

[stephanmullerNL]

Any news on this? I'm trying to find just a basic overview of what tags are at my disposal but even that is missing from the documentation, as far as I can tell.

[Gerrit0]

The StandardTags.ts file describes tags whose meaning is defined by tsdoc, I don't believe there is a spec yet.

[stephanmullerNL]

Thanks, that helps me a lot already

[RyanBellPOST]

Where is the spec?

[octogonz]

@RyanBellPOST actually we just finally finished API Extractor 7 this week. It took a lot longer than expected! I'll get started on the TSDoc spec draft once the dust has settled.

[qortex]

Just pinging here, do you have news to share regarding a tentative time schedule?

[aashkashah]

How do i generate documents using TsDoc ? Couldn't find user guide on CLI commands

[octogonz]

Just pinging here, do you have news to share regarding a tentative time schedule?

As far as a formal spec, there are still a few loose ends we wanted to sort out before writing everything up. The most significant change is a proposed improvement to the declaration reference syntax (outlined in uid.grammarkdown from https://github.com/microsoft/web-build-tools/pull/1337). The other issue is the support for HTML tags; originally TSDoc simply passed them through like Markdown does, but it's become clear that we need to fully parse them (https://github.com/microsoft/tsdoc/issues/138).

@MicMicMon I'm curious if you're looking for formal spec that can be used to implement a TSDoc parser, or if you're just looking for end user docs regarding the tags. If it's the latter concern, a lot of that is already written up between StandardTags.ts and API Extractor's docs; it wouldn't be much work to put it together in a consolidated doc. Let me know.

[octogonz]

How do i generate documents using TsDoc ? Couldn't find user guide on CLI commands

@aashkashah TSDoc standardizes the notation for doc comments in TypeScript. It's not a documentation tool by itself. If you're looking for a documentation generator that fully supports TSDoc, you could try API Extractor.

[qortex]

@MicMicMon I'm curious if you're looking for formal spec that can be used to implement a TSDoc parser, or if you're just looking for end user docs regarding the tags. If it's the latter concern, a lot of that is already written up between StandardTags.ts and API Extractor's docs; it wouldn't be much work to put it together in a consolidated doc. Let me know.

@octogonz Thanks for taking the time to reply!
Yeah, it's really for end user docs (quick reference with syntax to create links & co). Not strictly necessary as a lot is available through the links you give, I was just wondering if a self-sufficient doc was in the works. The traction on the SO post can be a good indicator if a metric is needed to prioritize this on a project management point of view.

Thanks for all the work!

@aashkashah I use compodoc and it is very nice.

[edjm1971]

Would you please be sure to include the proper format that should be followed when writing comments when Annotations are in use.
For example would we write comments as

/**
 * Description.
 */
@Component({...})
class MyClass{...}

Or would this be written as

@Component({...})
/**
 * Description.
 */
class MyClass{...}

According to the Comdoc website they show the 1st entry: https://compodoc.app/guides/jsdoc-tags.html

[octogonz]

@edjm1971 Good suggestion. Some related discussion is here: https://github.com/microsoft/tsdoc/issues/6

[octogonz]

To answer your actual question, I think we would agree with compodoc:

/**
 * Description.
 */
@Component({...})
class MyClass { ... }

The TSDoc comment should appear immediately before the declaration. In your example the decorator is best considered to be part of the declaration, similar to other modifiers like protected or export.

[harrysolovay]

Hi, I hope this isn't annoying (as I see other users have asked the same question at earlier dates), but I'm curious how the spec is coming along? I'm very curious & excited to see it, whenever it's ready.

[qortex]

Kind bump :) (fyi on the interest on the topic, the thread on StackOverflow is still actively visited)

[goldsam]

I don't understand how you have libraries, an eslint plugin, and a playground, yet no documentation or spec on what tsdoc syntax actually is. Am I missing something? I've combed the repository, but I'm struggling to make sense of this project.

[octogonz]

As noted above:

a lot of that is already written up between StandardTags.ts and API Extractor's docs

But yes, we really need to provide something better.

[octogonz]

Update: There's now a proper website https://tsdoc.org with documentation for all the TSDoc tags. More docs to come soon.

[qortex]

That is fantastic news, updated the StackOverflow answer accordingly. Thanks!