Is there a standard way to do a docblock for jQuery plugins?

Question

I am wondering if these is any standard for providing a docblock for jQuery plugins. And is it best to show how to pass in the config JSON object and should I explain the defaults?

e.g.

superPlugin v1.1

@author Me Myself

@options something

Can anyone provide any links?

Thanks

UPDATE

I've ended up just modifying the way jQuery does it

Answer 1

What i've seen so far that it was all written on top of plugin as multiline javascript comments like below, and there was no standards like wordpress plugins or so, or did i misunderstand your question?

/*
 * Metadata - jQuery plugin for parsing metadata from elements
 * Revision: $Id: jquery.metadata.js 3640 2007-10-11 18:34:38Z pmclanahan $
 */

and the description is always told in same way.

/**
 * Sets the type of metadata to use. Metadata is encoded in JSON, and each property
 * in the JSON will become a property of the element itself.
 *  * There are three supported types of metadata storage:
 *  *   attr:  Inside an attribute. The name parameter indicates *which* attribute.
 *   class: Inside the class attribute, wrapped in curly braces: { }
 *   elem:  Inside a child element (e.g. a script tag). The
 *          name parameter indicates *which* element.....
 */

Answer 2

There is the -vsdoc convention for standard Javascript files. When combined with the microsoft hotfix for Visual Studio, it can give intellisense.

http://blogs.msdn.com/webdevtools/archive/2008/11/07/hotfix-to-enable-vsdoc-js-intellisense-doc-files-is-now-available.aspx

There is a jQuery vsdoc function as well, which when included in your project gives intellisense on jQuery. It requires a certain standard of formatting, here is an example from the library:

// The number of elements contained in the matched element set
size: function() {
 /// <summary>
 ///  The number of elements currently matched.
 ///  Part of Core
 /// </summary>
 /// <returns type="Number" />

 return this.length;
},

The jQuery file is called jquery-vsdoc.js. This should not be shipped with any productions version of code.