Documenting JavaScript with jsdoc3

JavaScript is an extremely dynamic language which allows it to be applied in a variety of interesting ways. Some prefer to take the structured approach whilst others prefer an object-oriented approach using the prototype object or a library that offers a more classical approach. This diversity makes docblock type documentation seem impossible…but it isn’t!!

Thanks to jsdoc3 this task is made significantly simpler. It’s rich selection of tags makes it possible to document even the most abstract concepts that JavaScript permits. It is also extremely easy to create plugins and custom templates. Jsdoc is a command-line tool that works on any platform that supports Java. See project pages for information about usage.

Useful Links:

• jsdoc3 project on GitHub
• Documentation (under development)
• Discussion Forums

Using namespaces with jQuery Widgets

Creating plugins for jQuery is a relatively straightforward task, however poorly named plugins can conflict with one another (or even with core jQuery functionality). I have seen numerous attempts at solving this problem which each have their advantages and disadvantages.

My take on this problem is to define widgets in a completely separate namespace and then refer to them using a single jQuery plugin `widget`. This plugin depends upon the following jQuery variant of my `$namespace` function from here.

Improve consistency of button element across browsers

The button element can be styled easily for the desired look, however as soon as padding is specified the button appearance is drastically different across web browsers. So I did some searching and found several different fixes and found that a combination of all of them does the trick (mostly).

I have added the following to the end of Eric Meyers fantastic reset stylesheet.

/* Fix for IE7 */
button {
    overflow: visible;
    width: 0px;
    /* Default padding that can be overridden as desired. */
    padding: 2pt 4pt;
}
/* Fix for IE7+ */
button {
    width: auto;
}
/* Fix for FF */
button::-moz-focus-inner {
    padding: 0px;
    border: none;
}

I threw a crude test together and viewed it with Chrome, FireFox, IE9/IE8/IE7 and Opera and it seems to be a solved case. There are minor differences but it is certainly an improvement. IE7 still adds padding above and beneath button text. Please post a comment if you know how to fix that problem!

References:

• http://www.viget.com/inspire/styling-the-button-element-in-internet-explorer/ 
• http://www.aheadcreative.com/removing-unwanted-button-padding-in-firefox/