5

Closed

Convert C# style XML-doc comments

description

https://typescript.codeplex.com/SourceControl/changeset/view/45ec81e62ccef85b03b48d6f08c4ea94d33aeacd#src/compiler/text/textChangeRange.ts
    /// <summary>
    /// Initializes a new instance of <see cref="T:TextChangeRange"/>.
    /// </summary>
    /// <param name="span"></param>
    /// <param name="newLength"></param>
    constructor(span: TextSpan, newLength: number) {
https://typescript.codeplex.com/SourceControl/changeset/view/45ec81e62ccef85b03b48d6f08c4ea94d33aeacd#src/compiler/text/textSpan.ts
    /// <summary>
    /// Creates a TextSpan instance beginning with the position Start and having the Length
    /// specified with length.
    /// </summary>
    constructor(start: number, length: number) {
Basically, search for /// <summary> across the whole codebase, there must be a couple more files.

P.S. It would be lovely to stick some meaningful text in comments instead of useless placeholders like Initializes a new instance of <see cref="T:TextChangeRange"/> above. We all know the meaning of the word 'constructor', tell us something we don't know in those comments.
Closed Aug 7, 2013 at 7:54 PM by RyanCavanaugh
This bug has been fixed. If you're still seeing this issue, please re-open the bug (click "Re-open Issue" below the "ISSUES" tab). Thanks!

comments

robfe wrote May 6, 2013 at 1:29 AM

Are you asking the team to fix their own comments in their codebase, or are you asking for a feature whereby the TS compiler automatically converts C#-style comments into JSDoc style comments?

mihailik wrote May 6, 2013 at 7:31 AM

Yes, comments should follow JSDoc, as prescribed by the compiler. There isn't that many of C# comments to introduce a separate tool.

MgSam wrote May 6, 2013 at 3:01 PM

The documentation on the whole TS codebase in general could use some massive improvement. As a user it's not very important to me, but as an observer I have no idea how you can work with each other's code when most of the TS codebase is undocumented. JSDoc (and the resulting Intellisense) really is extremely helpful. Eat your own dog food, don't you know.

robfe wrote May 6, 2013 at 8:53 PM

@mikhailik then you have my vote, it's embarassing that TS's own codebase can't be more idiomatic.

RyanCavanaugh wrote May 6, 2013 at 9:31 PM

These comments pre-date us standardizing on JSDoc. We'll work on converting them, but it understandably isn't going to be a high priority.

mihailik wrote May 6, 2013 at 10:10 PM

Naturally, of course.

Although it would look ridiculous is it stays out of sync with your own spec for too long. My advise is to send a minion to spend an hour measuring the amount of work, then you'd know your budget.

Because another alternative is to remove those comments. Simple, cheap and rude, but at least it won't look weird anymore.

robfe wrote May 6, 2013 at 11:05 PM

@RyanCavanaugh Totally understand that you guys have more important things to work on: this is a nice-to-have. Will you take a pull request?

egil wrote May 7, 2013 at 11:21 AM

I actually created a tool that help convert vsdoc to jsdoc while I was trying to build type definitions for RxJS. It is not complete and does not support all vsdoc elements, but people more versed in parser building and/or regex can probably create something similar that process an entire JS file and replace all vsdocs with jsdocs in one run.

https://github.com/egil/VSDocJSDocConverter

WayneBloss wrote Sep 15, 2013 at 11:17 PM

Please implement vsdoc instead of or side by side with jsdoc.

Thank You.