JSDoc - Which Version?

Topics: General
Jan 23, 2013 at 5:45 AM

Love the integrated JSDoc intellisense support for Visual Studio in 8.2! As you know there is no official spec for JSDoc, so I was wondering which flavor of JSDoc the TypeScript implementation supports / is based on?

For example, are optional parameters defined with square brackets around the name?


 * @param {type} [name] description


Or with an equal sign in the type like the Closure Compiler?

 * @param {type=} name description
Optional parameters might seem like a bad example since that can be explicitly described in TypeScript, but if you're publishing your code as JavaScript with JSDoc comments baked in, this stuff is important.

Jan 23, 2013 at 4:17 PM

The only JSDoc tags we currently recognize are:

    @param name Description


    @param name {type} Description

Note that if you specify {type} here, we'll still show the *actual* type of the parameter.

We'll be seeing what people need and how people use the feature when deciding which additional things to recognize, if needed.

Jan 24, 2013 at 5:36 AM

Thanks for the answer.

Just to to give you some background, I'm rewriting Ext Spec in TypeScript. Partly because it greatly simplifies my build process, partly for the type safety, partly because it's cool ;)

I want the compiled JavaScript to ship with the JSDoc comments intact so the API is richer for anyone using the library in their own IDE (Aptana, VJET, Visual Studio etc.). So in that sense, I would love to see full JSDoc support, including optional @param tags, @property tags etc.

Jan 24, 2013 at 3:55 PM

For comment preservation, we would (or at least should, if we don't) leave the comment untouched.  This would let you pass the comments through to the output. 

The JSDoc support for 0.8.2 adds some parsing of the JSDoc to the Visual Studio experience.  Not all JSDoc makes sense for TypeScript, since a lot of information is in the TypeSystem and language features, so we likely won't support all of it, only the parts that make sense for TypeScript users.

That said, like Ryan says, we may add support for other tags that do make sense, based on user feedback.

Jan 24, 2013 at 8:33 PM
Edited Jan 26, 2013 at 6:55 AM

Yep, that's the behavior I've noticed. Using the -c flag on the compiler, the JSDoc comments are preserved more-or-less intact in the JavaScript output. (I'd like to see some more granular control over which comments are kept, but that's the subject of a different request :)

For now, I'm documenting everything the way I want it to be consumed, which includes @property tags and [optional] parameters. I'm getting some immediate benefits from this for my own development with 8.2, but as Ryan said, not everything is supported yet.

I guess what I'm saying is I want it all ;)

  • Richer intellisense for me writing the library in TypeScript.
  • Similarly rich intellisense for developers consuming the compiled JavaScript.
  • One version of the truth in terms of API documentation.
Jan 26, 2013 at 12:08 AM

Even better, the generated JSDocs in the .js files to be enriched with the metadata available in the .ts code. :)

Feb 20, 2013 at 5:04 PM
Boris, create an issue. I'd vote it up.