Add support for Xml Documentation in TypeScript

Topics: General, Language Specification
Oct 2, 2012 at 9:11 AM

Would be nice to get support voor XML Documentation inside TypeScript.
Something like this:

export class Point {
   /// <summary>This is a Point class.</summary>

    constructor (public x: number, public y: number) { 
        /// <summary>Creates a new Point object</summary>
        /// <param name="x"></param>
        /// <param name="y"></param>
    }
}

Oct 2, 2012 at 10:48 AM

You beat me to it :-). XML Documentation inside TypeScript would be very useful.

Developer
Oct 2, 2012 at 11:42 AM

We definitely would like to do this, but we're leaning towards using JSDoc formatting.

Oct 2, 2012 at 12:00 PM

What I like about the XML Documentation is when you type "///" it gives you a skeleton comment with parameters and return types etc.

I agree JSDoc makes sense in the produced javascript since it is ..... javascript after all. But from a typescript side the autogeneration of xml documentation could be very useful unless you can come up with "///" producing jsdoc notation ?

Of course Visual studio will need to parse the jsdoc and understand it.

Oct 2, 2012 at 12:04 PM

I would love to see support for JSDoc in here. Especially if VS2012 could be made to understand what the JSDoc was saying in the same way as intellisense includes information from XML documentation.

Oct 2, 2012 at 12:39 PM

JSDoc would even be better then Xml Documentation :)

Oct 2, 2012 at 1:34 PM
Edited Oct 2, 2012 at 1:36 PM

IMO, JSDoc is also much nicer than Xml documentation. In addition, I always thought having the docs inside of the functions was bizarre looking. (I understand the "benefit" is that you then have access to those docs at runtime, but how many people have ever used that feature?)

Would love to see you guys fully support /** */ style comments for XML doc generation in C# as well.

Oct 2, 2012 at 4:12 PM

+1 for jsdoc or vsdoc-style comments. I don't really care which you support. I just want my comments to augment Intellisense in Visual Studio, of course.

Also, I would love to see tooling for API generation within Visual Studio. Right now, there is basically jsdocToolkit for jsdoc and absolutely nothing available for vsdoc-style comments.

Oct 2, 2012 at 5:05 PM

Oh, yes!  Please switch to JSDoc instead of VSDoc.  It would be nice to be able to have these in a separate ".d.ts" file as well, if desired.

~~James

Oct 3, 2012 at 6:37 AM

With a UserVoice site it would be easier to gauge the interest for feature requests like these.

I think it may be better to have a TypeScript documentation format, which then converts to VSDoc or JSDoc. Some elements of JSDoc seem repetitive since typing can be inferred from the code. Two main arguments for the (additional) doc syntax would be IntelliSense support and standalone documentation.

Oct 3, 2012 at 9:57 AM

Please refrain from using any xml style comments. They are verbose, even when they are auto-generated. Please use the documentation style that is specific for node.js/javascript projects as used by the community.

Oct 3, 2012 at 1:24 PM

Agreed with @mr_much_win.  Also, do NOT invent yet another documentation format as @bgever suggests... that would be ridiculous.  Instead, I'd try to just have TypeScript auto-generate the known type info and inject it into existing JSDoc annotations.

Oct 3, 2012 at 2:17 PM

XML Documentation is more clear than JSDoc as it does not require two additional lines for opening and closing tags and does not require obsolete information to have 'correct' documentation. JSDoc is often used because you usually do not have any notion of types, but with TypeScript we do, and thus makes that notion completely irrelevant.

Oct 3, 2012 at 2:36 PM
Edited Oct 3, 2012 at 3:10 PM

Personally, I feel that JSDoc's "two additional lines for opening and closing tags" (/**, */) are a small price to pay versus the verbosity of XML.

Which is not to mention that the XML format requires `<summary></summary>` opening and closing tags that the JSDoc format does not (implied if untagged), so I'd say the line count is a break-even, if not worse (more lines) for the XML.

Oct 3, 2012 at 2:40 PM
Edited Oct 3, 2012 at 3:11 PM

The real trouble is that by perpetuating the Microsoft XML comment style, you're continuing to keep Microsoft operating differently than [probably] every other JavaScript consumer in the world (who use JSDoc). Since TypeScript is supposed to be more focused on Microsoft becoming a part of the community, and trying to keep in sync with the evolving ECMAScript 6 syntax, keeping this specifically different seems like it would be a poor choice that again keeps Microsoft at a distance from the actual community.

Oct 3, 2012 at 3:20 PM

+1 for JSDoc instead of XML docs.

Oct 4, 2012 at 6:23 AM

+1 jsdoc

- Infinity xmldoc

Oct 4, 2012 at 7:07 AM

TypeScript is not the same but similar to JavaScript. The JSDoc parser would need to be aware of TypeScript language constructs. Therefore, using plain JSDoc would not be optimal. Apples and pears, both fruit.

Using a similar syntax to JSDoc would be useful, but should allow (optionally?) to omit certain tags and elements like @constructor and type specifications, since they can be inferred from the code. The TypeScript compiler should be able to complete the 'JSDoc compatible format' to fully native JSDoc in the generated JavaScript. JSDoc toolkits can then be used as usual.

I also tend towards JSDoc, even though I'm very used to the XML documentation syntax from C#. However, to put the declaration inside code-blocks feels weird, and does not match the mental model for XML documentation in C# anyway.

Oct 20, 2012 at 5:27 PM

+1 JSDoc (simplified, since a lot of what JSDoc (or even XMLDoc) covers with it's annotations are already present in the TypeScript language itself).

JSDOc is already a standard, and most IDEs recognize it. It would be simpler to extend current JSDoc parsers to support TypeScript and thus help it spread quicker, not only on Microsoft's platform, but everywhere.

Microsoft is doing so well by not drifting away from standards lately that, IMHO, it would be a shame to drop the ball on this one.

Oct 22, 2012 at 6:59 AM

Take my vote for JSDoc!!! As it's a lot more "precise" and concrete. Also it would be great to get it autogenerated in the compiled js-files! 

Nov 7, 2012 at 8:44 AM

VSDoc is an unfortunate historical mistake, JSDoc is the way to go. Great to hear it's gonna be supported.

Nov 7, 2012 at 9:46 AM

I would argue that VSDoc comments should be used in the .ts files and that these should automatically generate JSDoc comments in the generated .js files.

VSDoc comments would go hand-in-hand with the VS extension which has already been made. There is no point it users who are already experiences with VS learning a new documentation format.

 

Another option is for the compiler to support both as the input type, but always generate JSDoc comments in the generated .js files.

Nov 7, 2012 at 10:05 AM

I would also prefer JSDoc instead of XML docs, as it is much more widely used & supported. (Not to mention verbosity of XML docs.)

Nov 7, 2012 at 11:26 AM

I want JSDoc in the output too, but in the actual TS files I want whatever VS supports natively. If that means VSDoc then so be it. It's more important for me that the code comments work in VS while coding. I don't want to maintain both JS and VS docs of course, but if it's the only way for now I'll do so until VS supports JSDoc natively.

Nov 7, 2012 at 12:35 PM

Good point, PhotonStorm. TypeScript team should probably try to persuade the JS tooling team that JSDoc is what the world is using for JavaScript doc comments, not VSDoc :) (Visual Studio could easily support both to maintain backwards compatibility.)

Nov 8, 2012 at 2:02 PM

That's true. I would definitely expect the TypeScript team to add JSDoc support to VS if they are going to centralize on it — which they should, and which their architect already voiced a preference for in this thread.

Nov 11, 2012 at 9:05 AM

No-one has yet provided a compelling reason why to choose JSDoc over VSDoc other than some very subjective "it's just better" or "it's more widely used" comments, or arguing towards verbosity (although my counter argument is that that verbosity begets greater legibility). It's like saying lets get rid of HTML in lieu of JavaScript just because HTML is verbose.

So here's my reasons why I think VSDoc would be a better bet for the TypeScript side of the argument (but I would agree that it should convert to JSDoc as best as possible when compiling to JS).

  1. VSDoc is widely used within the VISUAL STUDIO software dev community (C# and VB predominantly and starting to creep into C++ thankfully). One can argue that the tooling (such as ReSharper and so on) is already there and strongly supports VSDoc. Requiring Yet Another Documentation Format for people to learn and maintain is just silly. One can argue that there are likely more people out there who understand and use VSDoc on a daily basis compared to those who use JSDoc - so I disagree with the "it's more widely used" argument entirely.
  2. Visual Studio has wide support for VSDoc.
  3. Just like HTML, XML is a good way of describing document snippets (which documentation is) and is easy to parse visually. VSDoc is a document snippet format, JSDoc isn't and is therefore the better bet.

And then just to respond to some of the comments:

"It's a lot more 'precise' and concrete." - How-so? How is JSDoc more precise than VSDoc? They describe the same things in similar (but different) ways. JSDoc is no more or less 'precise' than VSDoc.

"VSDoc is a historical mistake." - Again, how-so? What makes VSDoc a "mistake" according to your view? Is it a mistake purely because it's not JSDoc? How is JSDoc superior, and give hard facts, not opinions.

"JSDoc is more widely supported compared to VSDoc" - By which segment of the current and potential future community? I would argue that VSDoc is far more widely supported than JSDoc purely because it's used by a HUGE portion of the current programming community *outside* of web and JavaScript development. If you're only choosing to look at a very small segment of the overall development community (ie. JavaScript developers only vs. .NET and C++ developers for example) then JSDoc is certainly more popular/readily supported.

"JSDoc should become the new standard for Visual Studio" - For what reason? VSDoc is already very powerful and capable. What benefits would introducing JSDoc have to the hundreds of thousands to millions of developers who are already familiar with VSDoc? What 'issues' would be solved by replacing VSDoc with JSDoc as the standard? Lets not be unrealistic.

My feeling is that one of the following options should be chosen:

  1. VSDoc as the documentation syntax for TypeScript, which can compile down to equivalent JSDoc into the JS files.
  2. The option for either VSDoc or JSDoc syntax in TypeScript (perhaps with compiler flag), with JSDoc being "copied" over to the JS and VSDoc being converted.

I think option 2 is probably the best since those familiar with either documentation system can then rapidly document in a familiar way while being secure in the knowledge that their documentation will be easily consumable by those tools that understand the JS side of the equation.

Nov 11, 2012 at 10:04 AM

Tharaxis, don't confuse XML Documentation Comments in C# and VSDoc which is an xmldoc-inspired syntax created specifically for JavaScript. What is probably OK in C# is so very not OK in JavaScript.

In the world of JavaScript libraries, they are either not doc-commented at all, or use JSDoc. Just have a look around. Most of the JavaScript community *today* doesn't use Visual Studio - they love tools like WebStorm, Sublime Text, Vim etc. They are also often on OSes other than Windows so a large part of the community will never get to use Visual Studio, and they will always be using JSDoc, not VSDoc.

If TypeScript / Visual Studio wants to be a welcome citizen in this community, they cannot try to force some proprietary, mostly unknown format on it. If you look at TypeScript syntax, I think it is evident that it has been very smartly designed - although they (at least Anders) have .NET / C# very deep under their skin, they rightly decided not to push .NET conventions, quite to the contrary, TypeScript feels very natural for JavaScript developers. It is only logical that they do the same with doc comments, and it was great to see that the team is aware of this (see the comment of Anders above).

Nov 11, 2012 at 10:17 AM

One of the main benefits that TypeScript sells itself on is its ability for JS and TS to coexist happily in the same file. Being able to use any of the hundreds of thousands of JS libs out there without having to convert them all to TS first. By ignoring the documentation standard that they use we then have to manually convert all of those docs to VSDoc format just to be able to use them easily in VS after which they would then be converted back to JSDoc again on build. That seems nuts really.

 

I agree there are lots of VSDoc tools in existence, and I've nothing against the format (despite its verbosity) and I don't want to see JSDoc replace it across the board, but TypeScript is a unique case and needs handling as such.

Nov 11, 2012 at 10:34 AM

You know, I must say I did get my lines crossed. If you are referring to the current JS documentation syntax within Visual Studio, I agree, it's horrible and should not be used whatsoever. I agree in the sense that any JS output should not use that and should rather conform to whatever community standard has already been set up (in this case that "standard" would be JSDoc) - ANY documentation format defined within TypeScript should ultimately output JSDoc.

*However* let me rather retool my original argument then. I feel that the documentation syntax already utilized within C# and so on is what should ultimately be treated as a first-class documentation syntax within TypeScript - it's widely used, widely supported within the tools MS will want to directly target (namely their own), and is widely understood within a large community of developers who maybe want to do JS, but don't know how or have not liked the peculiarities of the language. This does *not* mean that JSDoc cannot also be welcome within that environment, just that MS should not choose to forget their existing developers - if anything it's their existing developers that they're trying to appeal to with this.

Lets not get confused here however, TypeScript is *not* JavaScript, even if it's incredibly close - so it is unnecessary to too strongly foist JS conventions on to the language - a language, mind you that is trying to expand the community of those that understand and can produce JS to those who traditionally would not use the language due to its inability to scale to large projects or conform to a more statically-typed idiom. Sure, TypeScript is for existing JS developers, but it's more specifically for those developers who don't do JS now, but would like to (but have skill in other aspects of development that vanilla JS does not tend towards). Sure, the goal right now is to bring the ideas behind ECMAScript 6 to browsers today (but all the static typing goodness is already outside of spec), but while that is a good starting point I think it's a little too limiting - eventually, if MS supports TS as a first-class language within their tools (which I do hope will happen and believe will) they will eventually try and make it do more.

Finally, let us not confuse personal desires with those of the "community" (let each man speak for themselves, I say), and I find it slightly insulting, arrogant and short-sighted that you believe that the community would ignore TS (a useful tool in its own right) purely because it happened to have a different documentation syntax to what they're already familiar with - I would not stop using TS just because it chose JSDoc for example. Maybe individuals would - that would be their loss however - but I feel having an inclusive approach where both documentation styles are supported would be more valuable. I've been a part of this "community" (what community exactly - the JS community??) for approaching 11 years now and your desires certainly don't mirror mine.

Nov 11, 2012 at 10:45 AM

Hi photonstorm

I agree, there are many libraries that use JSDoc right now, and getting some intellisense within the typescript editors that reflect what is described in the JSDoc comments would be awesome. TypeScript consists of multiple "spheres" however that documentation would touch.

  1. When consuming JS libraries, providing intellisense through JSDoc makes sense since the community is already using this.
  2. When compiling TS to JS, outputting JSDoc makes sense since the community expects this for their own tools.
  3. When consuming TS definitions (used predominantly to describe existing JS libraries), nothing has been defined - being able to generate documentation FROM JSDoc however would be great.
  4. When consuming TS libraries, nothing has been defined.

For points 3 and 4, there is no documentation format yet, so there is no need to settle on one or the other, and as long as the resulting JavaScript contains JSDoc and only JSDoc I see no reason for there to be an argument on the matter other than for the purposes of starting holy wars. It eventually comes down which is easier to implement and easier to use. I suspect going JSDoc throughout would mean easier implementation (since you only have to worry about 1 documentation standard instead of 2), but it does serve to get in the way of those who are established within the C#/.NET way of doing things - since MS has decided to also roll out this documentation format for C++ I see no reason that this documentation format would not become a first-class citizen within TS.

Nov 11, 2012 at 10:45 AM

I did not say that the JS community would reject TypeScript only because of the doc comments syntax. I said that IMO, TypeScript should try to feel as natural as possible to JS developers, including doc comments syntax. That is all.

Nov 11, 2012 at 10:51 AM

broekb, on that I can agree. No harm no foul.

Nov 12, 2012 at 11:15 AM
Edited Nov 12, 2012 at 11:19 AM

Keep in mind that the TypeScript editor is Microsoft-supported in not only Visual Studio but also in SublimeText2, Emacs, and Vim.  The likelihood of developers utilizing those latter three IDEs/editors knowing the VSDoc comment style (vs. the defacto standard JSDoc) is pretty much zero.  However, again, in trying to be part of the greater JS community, Microsoft added support for these non-Microsoft IDEs/editors in an attempt to gain more foothold and feedback because they know that most of the JS community doesn't use Visual Studio for JavaScript development.

Don't get me wrong: I love Visual Studio for C# and ASP.NET development but its Intellisense for JS is total crap without having Resharper 6+ installed.  For JS development, I fallback to the very excellent WebStorm instead.

Nov 27, 2012 at 7:30 PM
Edited Nov 27, 2012 at 8:20 PM

+1 jsdoc

I believe Anders and the TypeScript team made the right call when choosing to make TypeScript a super-set of the javascript language.  It allows for almost seamless transition between the two languages.  Choosing jsdoc for the comment documenting system follows this philosophy.  A majority of the great javascript libraries and components are currently written outside of VisualStudio and even Windows.  These libraries, when documented, almost always chose jsdoc.  

Microsoft has been know for the 3 Es. I'd like to seem the focus heavily on Embracing and only when all viable community based solutions haven been considered and attempted, Extend.  

Top jsdoc feature requests:

  • Intellisense should display descriptions & metadata retrieved from jsdoc, like it does from C# commented with ///
  • Visual Studio IDE should add snippet creation support for jsdoc, similar to typing /// in C#.
  • Add typescript compiler option to include jsdoc comments in compiled js files
  • Automatically include jsdoc tags which can be infered from the source, such as @namespace, @module, @class, @constructor, @method, @param {types} []
  • Add typescript compiler option to add warnings for undocumented symbols

Pie in the sky feature requests (either):

  • Add real-time jdsoc to declaration interpretation
  • Create a tool which can export typescript declaration files from jdsoc

I am currently working on an open source project to solve the last feature.  My goal is to be able to export typescript declaration files from libraries documented with jsdoc.  This would save the DefinitlyTyped community a great deal of time.  Also, if it is a simple as running a node app during build, it may encourage the javascript library authors to embrace generating and distributing declaration files with their assemblies.

https://github.com/joshheyse/jsdocts

Dec 2, 2012 at 1:18 PM

There is point to the suggestion for a new document format. Here is a comparision of JSDoc and VSDoc using an example from a JSDoc tutorial:

 

// Stats: lines = 4, characters = 248
module VSDoc {

    export function repeat(str: string, times: number = 1): string {
        /// <summary>Repeat <tt>str</tt> several times.</summary>
        /// <param name="str" type="String">The string to repeat.</param>
        /// <param name="times" type="Number" default="1">How many times to repeat the string.</param>
        /// <returns type="String" />

        if (times < 1) {
            times = 1;
        }
        return new Array(times + 1).join(str);
    }
}

// Stats: lines = 6, characters = 172
module JSDoc {

    /**
     * Repeat <tt>str</tt> several times.
     * @param {string} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */
    export function repeat(str: string, times: number = 1): string {
        if (times < 1) {
            times = 1;
        }
        return new Array(times + 1).join(str);
    }
}

From the above it is clear that VSDoc is more verbose in terms of the number of characters in the body of the documentation, but JSDoc requires 2 additional lines. More importantly both types carry rather a lot of redundant baggage - highlighted in red above. Clearly it does not make sense to simply institute either of these documentation formats in their present form. The documentation above relates to a single function, and it's not too difficult to imagine how this will play out when applied to 20,000 lines of code.

Removing the redundant information from the JSDoc example, and making a slight change to the document line prefix we have:

// Stats: lines = 3, characters = 129
module TSDoc {

    /// Repeat <tt>str</tt> several times.
    /// @param str The string to repeat.
    /// @param times How many times to repeat the string.
    export function repeat(str: string, times: number = 1): string {
        if (times < 1) {
            times = 1;
        }
        return new Array(times + 1).join(str);
    }
}

The new format has half the number of lines as JSDoc and 25% fewer characters. The format is also, one hopes, not too foreign for either the JSDoc or the VSDoc camps.

I strongly urge the TS team not to sully TypeScripts reputation by implementing JSDoc. There is a large body of respectable people out there that has never used JSDoc; and the block comment syntax (and all the corresponding asterisks) appear rather clumsy and old fashioned - harking back to stuff found lurking in C++ header files. The horror! 

Of course the compiler can be made to emit one or the other documentation formats into the compiled JavaScript file.

Thanks.

Noel

Jan 1, 2013 at 9:38 PM

Dont really mind which one, but this would be really useful!

Jan 8, 2013 at 5:41 AM
Edited Jan 8, 2013 at 5:45 AM

@nabog: wow, that's a really excelent implementation .   hope mr H and the typescript crew read it and strongly consider!

 

i think the best would be to support your /// format, in addition to parsing "normal" jsdocs that may be pasted in from legacy js codebases.

Coordinator
Jan 8, 2013 at 3:52 PM

This is currently being worked on for the next release.  I do like nabog's suggestions, but we ultimately were concerned that it mixes JSDoc style with a VSDoc triple slash, which might be confusing.  Agreed we do want to simplify and not require the type in the JSDoc, so it's now optional, giving you this for the above:

module TSDoc {

    /** Repeat str several times. 
* @param str The string to repeat.
* @param times How many times to repeat the string.
*/
export function repeat(str: string, times: number = 1): string { if (times < 1) { times = 1; } return new Array(times + 1).join(str); } }
Jan 8, 2013 at 6:52 PM
Edited Jan 8, 2013 at 8:41 PM

Perhaps we can do away with the asterisk on each line as well? They seem to perform a purely decorative function and are made redundant by the fact that each subsequent line after the title begins with @param.

 

 

module TSDoc {

   /** Repeat str several times. 
       @param str The string to repeat. 
       @param times How many times to repeat the string. 
    */
    export function repeat(str: string, times: number = 1): string {
        if (times < 1) {
            times = 1;
        }
        return new Array(times + 1).join(str);
    }
}
Jan 9, 2013 at 1:57 AM

@jonturner: Excellent to see feedback from the dev team, and I'm happy to see you consider compatibility and clarity over efficiency.

For the provided TSDoc example, how would this look in the generated JavaScript file? Will there be JSDoc comments, and will those be completed with type information inferred from the code and overridden if types are explicitly defined in the TSDoc comments?

Coordinator
Jan 9, 2013 at 5:21 PM

@nabog, each subsequent line doesn't necessarily start with an @param.  For example, you could have a multiline comment for one of your params.

module TSDoc {

    /** Repeat str several times.
      * @param str The string to repeat.       
      * @param times How many times to repeat the string. 
      * Values of zero or below are silently ignored.
      */
    export function repeat(str: string, times: number = 1): string {
        if (times < 1) {
            times = 1;
        }
        return new Array(times + 1).join(str);
    }
}

 @bgever, for this next release we're mostly focusing on getting the IDE experience in place, so that you'll be able to see the parsed comments as part of the intellisense experience.  For comment preservation, we aren't currently working on outputting fleshed out JSDoc.  Do you have places in your project you'll need this?

Jan 9, 2013 at 8:33 PM

@jonturner, well yes. That did occur to me.

I presume that in order to parse the block comment one needs to know the following:

- What is the title string? Answer: Parse from the beginning until the first @param.

- What is the first parameter? Answer: Parse from the first @param until the next @param

Repeat until the closing slash.

It's not clear why the asterisk on each line is necessary.

It seems to be purely a whim on the part of the inventor of this monstrosity! :)

 

Noel

Jan 10, 2013 at 12:09 AM

agree with nabog,

though since i'm a VS user, if VS could auto-format my asterisk's (similar to how it does c# ///<docs> ) that'd be fine by me.

Jan 10, 2013 at 1:56 AM
jonturner wrote:

 @bgever, for this next release we're mostly focusing on getting the IDE experience in place, so that you'll be able to see the parsed comments as part of the intellisense experience.  For comment preservation, we aren't currently working on outputting fleshed out JSDoc.  Do you have places in your project you'll need this?

I can see places where it would be useful to have comment preservation, although I personally do not have a big need for this now;

  • While debugging generated JS via browser tools, the comments will assist a lot.
  • JS developers will find it easier to make dependencies on TS generated scripts.
  • JSDoc automatic documentation generators will work on the generated JS, without having to support TS.
Jan 10, 2013 at 10:04 PM
Edited Jan 10, 2013 at 10:06 PM

If TypeScript is going to support JSDoc it should support JSDoc- period. Not some variant of it. One of the main benefits of having it support JSDoc is so there's compatibility with existing tools (including Google's Closure compiler).

I think something the compiler could and should do is insert the type into the comments upon compilation. 

Thus,

 

 /** Repeat str several times. 
  * @param str The string to repeat. 
  * @param times How many times to repeat the string. 
  */
 function repeat(str: string, times: number = 1): string {
    if (times < 1) {
        times = 1;
    }
    return new Array(times + 1).join(str);
}

 

becomes

/** Repeat str several times. 
  * @param str {String} The string to repeat. 
  * @param times {Number} How many times to repeat the string. 
  */
 function repeat(str, times): string {

    if(times === undefined) times = 1
    if (times < 1) {
        times = 1;
    }
    return new Array(times + 1).join(str);
}
after it's compiled. This would save time and synchronization issues on the part of the developer. The last thing I want is to have to remember to change the type in both the method signature and in the JSDoc comments every time I make a change.

Jan 10, 2013 at 11:55 PM

@mgsam: especially since the doc system jonturner describes is so close to jsdoc,  I assume that this simplification, AND "full" JSDoc will be supported.

Coordinator
Jan 11, 2013 at 11:38 PM

@MgSam I should have also mentioned that the @param we support does also allow you to put in the type as is specified in other JSDoc implementations, so it does align there.  We don't have support for other @ attributes, yet, but more may come as needed.

There's a feature request tracking JSDoc and VSDoc output, so that might be a good addition to add to that (if you haven't already).

Jan 12, 2013 at 7:49 AM

@jonturner:

I like what I'm seeing. 

I would like to suggest that in Visual Studio, these comment blocks be collapsible regions (just as they currently are in C#).

Nick

Jan 12, 2013 at 4:54 PM

They've gone for JSDoc, naturally.

http://typescript.codeplex.com/discussions/429373

Jan 24, 2013 at 11:32 AM

XML is a fantastic format for programs to create, so that other programs can consume.

If a person ever has to read raw XML, then that is a tragedy.

If a person ever has to hand-create XML or hand-modify XML, then that is a dismal state of affairs.  Only in dire and rare circumstances should that ever be necessary.

That includes snippets of inline XML as source code documentation.

+1 JSDoc

Jun 27, 2013 at 9:31 AM
Edited Jun 27, 2013 at 9:32 AM
Guys,

I know it's a small "thing" but I'm not getting auto indentation or other Intelli-type stuff (like adding another line of comments on pressing enter) in VStudio 2012 for JSDoc comments.

Does this happen to you also or is this clash with another one of my plugins?

Thanks
Jun 28, 2013 at 1:41 AM
i had a number of problems with 0.9.0 performance, which could cause intellisence to misbehave.

or, if you are using plugins like resharper, that could cause issues too

some things to try: clean your solution, close visual studio, delete .suo file.

you could also try 0.8.3.1, if you can live without generics it's much more stable
Jul 17, 2013 at 3:58 PM
I just created a tutorial on how to create TypeScript documentation with YUIDoc's: http://www.codebelt.com/typescript/generate-documentation-for-typescript/
Jul 18, 2013 at 4:54 AM
good effort, but I'd expect a proper typescript doc system to take advantage of the typings / metadata typescript provides. to me, needing to re-implement the signatures inside a documentation block is a non-starter
Sep 15, 2013 at 10:12 PM
Hey, there's a ton of people who like XML comments better than JSDoc.

Can't we just have both please?
Dec 23, 2013 at 2:28 AM
Edited Dec 23, 2013 at 2:31 AM
After reading this topic I agree that JSDoc makes more sense. It is more clear and TypeScript is almost Javascript. Makes sense to keep only one.
    /// <summary> Text text and more text
    /// new lines as well
    /// <param> The name is on the method, so is the type
    /// cool
    /// <param> Another parameter
    /// nice
    /// <param> Hey I don't exist, compilation error?
    /// <remarks> This looks nice
    /// or not?
    /// <returns> Something, you know my type it is just below
    Foo(public x: number, public y: number): Bar
    { 
    }
    /// @summary Text text and more text
    /// new lines as well
    /// @param The name is on the method, so is the type
    /// cool
    /// @param Another parameter
    /// nice
    /// @param Hey I don't exist, compilation error?
    /// @remarks This looks nice
    /// or not?
    /// @returns Something, you know my type it is just bellow
    Foo(public x: number, public y: number): Bar
    { 
    }
I wrote the above codes to check what is looks like, I was also thinking what it would be like in C#. I'm guessing both look awful...
Feb 1 at 7:04 AM
I personally would prefer XML documentation, with a schema specialized for TypeScript constructs such as generics which aren't supported in JavaScript.

Either way, for this to be useful, there has to be a way to have the documentation template automatically generated, in much the same way /// comments are.