Current state of the project?

Hello everyone! Super excited about this project. I’d love to get involved in any way I can.

I tried to install & run tsdoc locally, and ran into issues. So, I wanted to know - is there a roadmap available with planned features / support + implemented features / support? I’m asking both so I can debug the issue I ran into, and so I can reference it when looking for ways to contribute =)

Thanks for the hard work everyone!

[octogonz]

(We’ll try to give more frequent updates going forward. Something was broken with my GitHub notifications, so I just noticed your question today.)

Status: I’m currently working on the initial architecture and prototype for the parser library. Once we have a working prototype, it will be in a good state to accept pull requests / feedback from the community. Until then it’s a little hard to collaborate unless someone is in the Seattle area and wants to meet up.

I was making pretty good progress until I ran into some questions about how to model the AST, specifically handling of mutiline tokens whose “lines” are embedded inside a doc comment, for example:

  /**
   * `abc
   * def`
   */

(Is abc def a single lexical token? Is the * part of that token?)

We met with the TypeScript compiler owners, and they gave a bunch of really helpful feedback. They also suggested that we build the tsdoc NPM package as an extension of the compiler’s AST, rather than having it act as a standalone parser. It would still be its own library, but the input would be a TypeScript compiler data structure instead of a plain text string (as in the current approach).

Integrating with the compiler has some benefits:

• More involvement and help from the compiler team
• Leverage a sophisticated existing framework that includes a lot of helpful utilities
• Simpler roadmap for integrating TSDoc support into the compiler and VS Code

But there are also drawbacks:

• A bigger learning curve to get off the ground
• The tsdoc package would become coupled to a specific release of the compiler
• If we need to make patches to the compiler to get our problems solved, we’d have to depend on an unstable release of the compiler until our patches finally reached production
• Any changes we need to make in the compiler would demand a high quality bar, and force us to consider requirements that aren’t immediately relevant to a documentation tool (e.g. IntelliSense)

It’s a tough call. My coding progress stalled while I researched this decision, and then recently I got sidetracked by some other priorities. TSDoc is now my primary focus again for the rest of June, but then in July I will be away on vacation for a few weeks… so the short answer is that it’s moving along, but probably won’t take off until later this summer.

I will say that we now feel reasonably confident about the initial language spec for TSDoc, and also the overall parsing strategy.

I’d love to get involved in any way I can.

The easiest way to contribute right now is to open/answer GitHub issues that help us flesh out the requirements and syntax for the TSDoc notation. There are still plenty of interesting edge cases and cool feature ideas. If you maintain a documentation tool, you can also compare/contrast your syntax and features against what we’re proposing for TSDoc and identify any gaps.

[octogonz]

I have added a Where are we on the roadmap? section to the root-level README file, which people can use to track our progress until we get a proper newsfeed set up.

Here’s what I posted there as of today:

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

As such, I’m going to close this GitHub issue.

BTW I’m also excited to announce that we made a cool little TSDoc Playground with an interactive demo of the parser. (Big thanks to @iclanton and @KevinTCoughlin for their work on this!) Enjoy! 😛