Full example of a class definition, including JSDoc
// declare the module (also ensures existance of foo.bar) jQuery.sap.declare("foo.bar.MyClass"); // declare and document the constructor function /** * Some short sentence that summarizes the functionality of the class. * * A more detailed explanation of the class that might consist of multiple sentences * and paragraphs. It is <i>possible</i> to use <code>XHTML</code> <b>markup</b> * but this should be used only rarely, as it makes the doclet harder to read * in the JS editor. * * Paragraphs that are separated by empty lines will be formatted as separate * paragraphs in the final JSDOC documentation. This makes the addition of * <p> or <br/> tags unnecessary. * * It is possible to reference members of this class (like {@link #ownMethod}) * or even of other classes (like {@link sap.ui.Object#destroy}). But be careful: * in contrast to JavaDoc, the signature (parameters) of a method must not be * included with the @link tag, only the name of the method (as !JavaScript does not support * method overloading). * * @class (mandatory) Marks the function as a constructor (defining a class). * @param {string} sId Documentation of constructor parameters. * @param {object} [mProperties=null] For optional parameters, the name is enclosed * in square brackets. * A default value can be appended with a '='. * @param {string} [mProperties.text] Even members of a configuration parameter * can be configured. * @see (optional, multiple) Fully qualified HTTP links to external documentation * are also possible. * * @public|@private - (optional) Declares the class as public or private (default). * @author (optional, multiple) Author is referenced by user Id, not by name. * Multiple authors are possible, order is * significant (first named author is the default * contact). * @since (optional) When the class/function has been introduced. * @extends sap.ui.base.Object Documents the inheritance relationship. * @name foo.bar.MyClass (Mandatory when defining a class with extend). */ sap.ui.base.Object.extend("foo.bar.MyClass", /** @lends foo.bar.MyClass */ { constructor: function(sId, mProperties) { // init and document members here /** * The ID of a MyClass. * * @private */ this.mId = sId || Utils.createGUID(); }, // now add further methods to that prototype /** * Again a summary in one sentence. * * More details can be documented, when the method is more complex. * @param {string} sMethod The same mechanism as above can be used to * document the parameters. * @param {object} [oListener] An optional parameter. If empty, the * <code>window</code> is used instead. * @experimental Since 1.24 Behavior might change. * @public */ ownMethod: function(sMethod, oListener) { // ... impl }, /** * A private method. * * Every member with a doc comment is included in the public JSDOC. * So we explicitly declare this as a private member: * * Additionally, using an underscore prefix prevents this method * from beeing added to the public facade. * * @private */ _myVeryPrivateMethod: function() { } });
/** * A 'virtual' method, that doesn't exist in this class but should be declared * in subclasses. * * It is even possible to document things that aren't there. Only useful use * case is the documentation of abstract methods. * * @name foo.bar.MyClass.prototype.abstractMethod * @function * @protected */