So I have been playing around with Visual Studio 2012 developer preview recently. From a SharePoint developers perspective, there are a lot of new features which will improve the productivity such as the List Designer, Remote Deployment of Solutions etc. Also, from a JavaScript developers perspective, there are a truck load of new features which make your life quite easy and productive. Visual Studio 2012 treats JavaScript as a first class citizen with functionality such as Intellisense and 'Go to function definition'.
One of the exciting features is the XML documentation comments functionality which allows the developer to provide XML comments to functions which the Intellisense picks up and displays accordingly. Also, more than one signature can be displayed for overloaded functions. Lets have a look at an example:
One quirky thing is that we have to put the documentation inside the function. The <signature> element describes the documentation for one implementation of the function. The <summary> element describes the description of that implementation. The <param> element describes the details about one parameter of the function. The <returns> describes the type of the value which the function returns. And as you can see from the following image, the Intellisense does indeed pick it up and display the documentation accordingly.
One of the exciting features is the XML documentation comments functionality which allows the developer to provide XML comments to functions which the Intellisense picks up and displays accordingly. Also, more than one signature can be displayed for overloaded functions. Lets have a look at an example:
Here is the complete list of elements supported by the
<signature> element:
Also, the XML documentation functionality goes beyond the signatures. Here is the complete documentation available right now:
3 comments:
I would like to quote Jeff Atwood here "if your feel your code is too complex to understand without comments, your code is probably just bad." (http://www.codinghorror.com/blog/2008/07/coding-without-comments.html). Besides, the above has some serious issues. There is no static typing in JS so if your comments say that firstName is of type string then that is wrong. firstName could be of any type. In JS, it does not matter how many parameters you pass to a function, if the name of the function is correct and it can be found on the execution context chain, the function would be executed no matter if not all the parameters are provided. There is no easy way to provide a standard way of commenting a dynamic language like JS. Better option - Let your code speak.
P.S. - Sorry for being rude and direct
Hi Suhas. How are you? Very valid points and I partly agree with you. Yes JavaScript is a dynamic language as in we can pass parameters of any type and they will be valid. But that will not account for the function returning valid values. If a function is going to return the addition of two numbers, and a string is passed instead of one of the numbers, the resulting value will not be what is expected from the function. Another example is that a geolocation function pin points a persons location based on the latitude and longitude provided as parameters. If only the latitude is passed, then JavaScript will execute the function, but the result will not be as expected. I think in these cases, documentation can help.It will help the developers call the functions appropriately (maybe if they are working on some one else's library) I decided to keep the demo example very simple so that the main focus could have been on the documentation. And lastly, I absolutely agree that your code should be the documentation it self.
@Suhas This isn't about code being too complex to understand, this is about someone using your API without looking at your code. Documenting an API is by no means a waste of time. Also, just because you can pass any types into a JavaScript function doesn't mean you should. Knowing the parameter types that a function expects and returns is even more helpful in JavaScript than a compiled language such as C#. Your post is wrong on many levels.
Post a Comment