locked
What is the recommended way to document javascript code? RRS feed

  • Question

  • I used to use YUIdoc/jsdoc style to document javascript code, but I see that WinJS uses xml comments (just like in C#). Unfortunately, Visual Studio doesn't provide any help in generating those comments in js (writing ///, like in C#, doesn't work).

    So I wonder if there are any recommendations and/or tools for documenting WinJS code.

    Monday, December 24, 2012 3:34 PM

Answers

All replies

  • Hi,

    Please make sure you are using VS2012. That support javascript  very good.


    Roy
    MSDN Community Support | Feedback to us
    Develop and promote your apps in Windows Store
    Please remember to mark the replies as answers if they help and unmark them if they provide no help.

    Tuesday, December 25, 2012 7:13 AM
  • Hi,
    I'm using VS2012 Pro.

    Let's assume the code snippet below is what I want to document.

        WinJS.Namespace.define("Test", {
            doWork: function (args) {
                return "something";
            }
        });

    I want to provide descriptions for the doWork function itself and arguments it expects. It would also be nice if those desciptions could appear in the Intellisense tooltips. How do I do this?

    I suppose this can be achieved by using xml comments. For example here is how WinJS.xhr function documentation looks like in base.js:

        WinJS.Namespace.define("WinJS", {
            xhr: function (options) {
                /// <signature helpKeyword="WinJS.xhr">
                /// <summary locid="WinJS.xhr">
                /// Wraps calls to XMLHttpRequest in a promise.
                /// </summary>
                /// <param name="options" type="Object" locid="WinJS.xhr_p:options">
                /// The options that are applied to the XMLHttpRequest object. They are: type,
                /// url, user, password, headers, responseType, data, and customRequestInitializer.
                /// </param>
                /// <returns type="WinJS.Promise" locid="WinJS.xhr_returnValue">
                /// A promise that returns the XMLHttpRequest object when it completes.
                /// </returns>
                /// </signature>
                var req;
                return new WinJS.Promise(
                    function (c, e, p) {
                        /// <returns value="c(new XMLHttpRequest())" locid="WinJS.xhr.constructor._returnValue" />
                        req = new XMLHttpRequest();
    

    In C# it's possible to write three slash symbols (///) right above the method declaration and that would generate placeholder with xml comments for that method, so you only need to write you descriptions without worrying about all those xml tags.

    In javascript, however, same approach doesn't work.

    Tuesday, December 25, 2012 12:06 PM
  • There is a VS Extension that does what you need: JScript vsdoc Stub Generator

    Never tried it myself but sounds like it will fit your needs.
    Wednesday, December 26, 2012 1:52 PM
  • See this for more info:

    http://msdn.microsoft.com/en-us/library/ie/bb385682(v=vs.94).aspx

    You can add intellisense!


    Jeff Sanders (MSFT)

    Wednesday, December 26, 2012 8:36 PM
    Moderator