Documenting Javascript doc comments


Bertrand Leroy, a Software development Engineer, from AJAX team is currently representing Microsoft at the OpenAjax Alliance working group. You can read about the working group’s intentions and planning here: http://www.openajax.org/member/wiki/IDE_Charter.


Today Bertrand bloged about the format of Javascript doc comments. Xml documentation annotations are going to drive JavaScript IntelliSense in Visual Studio Orcas (the next version of Visual Studio). For more than a year now, we’ve been including xml doc comments to all public APIs in the Microsoft Ajax Library (which are a great place to check out some examples of those comments). You can get more information at his blog http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-comments.aspx.


I have been working with Bertrand to find ways for Sandcastle to generate documentation for Javascript doc comments. He has developed a cool document extraction tool that will generate reflection.org file for Sandcastle. Look for more details in his blog and my future blog.


 Anand..



 

Comments (1)

  1. Filip says:

    Anand,

    I’ve been using Sandcastle, and it works really well.

    Off course, Sandcastle is dependent on the quality of its input. And since you are so intimately involved with the XML documentation of Visual Studio code, here’s a straightforward but SO useful feature request (for the Visual Studio team?). I hope you pass it along, because it really impacts the usefulness of Sandcastle directly:

    ///<Start request>

    Would it be possible to have WYSIWYG HTML editing of XML documentation of C#/VB code please.

    ///</End request>

    So when I write ///<summary> or any other tag, it would be really great to get a rich text box where I could type AND FORMAT the comments as WYSIWYG as possible.

    It doesn’t matter if this is in a properties windows, in a popup, in a split view, really anything that the team can pull off rather quickly would be hugely appreciated. It would be so nice if we could have a rich text box for each XML section, instead of handcoding HTML and XML, or cutting and pasting back and forth all the time.

    The team can focus on deeper integration later if appropriate.

    The ideal solution is off course if the documentation is rendered WYSIWYG inline in the code, so that you see the documention and code right there together.

    Sandcastle adds a lot of info, such as the hierachy, which may be CPU-intensive to do on the fly. And that’s fine, Sandcastle augments documentation for external consumption. But simply displaying in rendered HTML the comments typed in as documentation would already be a HUGE help for us poor developers who need to WRITE the documentation.

    I’ll stop repeating myself. Thanks and keep up the good work.

    Filip.