-
Notifications
You must be signed in to change notification settings - Fork 130
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Where are TSDoc syntax specifications? #130
Comments
From the README.md:
|
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. |
Great, thanks for the awesome achievements! |
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. |
The StandardTags.ts file describes tags whose meaning is defined by tsdoc, I don't believe there is a spec yet. |
Thanks, that helps me a lot already |
Where is the spec? |
@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. |
Just pinging here, do you have news to share regarding a tentative time schedule? |
How do i generate documents using TsDoc ? Couldn't find user guide on CLI commands |
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 microsoft/rushstack#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 (#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. |
@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. |
@octogonz Thanks for taking the time to reply! Thanks for all the work! @aashkashah I use compodoc and it is very nice. |
Would you please be sure to include the proper format that should be followed when writing comments when Annotations are in use.
Or would this be written as
According to the Comdoc website they show the 1st entry: https://compodoc.app/guides/jsdoc-tags.html |
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 |
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. |
Kind bump :) (fyi on the interest on the topic, the thread on StackOverflow is still actively visited) |
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. |
As noted above:
But yes, we really need to provide something better. |
Update: There's now a proper website https://tsdoc.org with documentation for all the TSDoc tags. More docs to come soon. |
That is fantastic news, updated the StackOverflow answer accordingly. Thanks! |
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
The text was updated successfully, but these errors were encountered: