PageRenderTime 17ms CodeModel.GetById 12ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/wiki/CookBook.wiki

http://jsdoc-toolkit.googlecode.com/
Unknown | 136 lines | 119 code | 17 blank | 0 comment | 0 complexity | 8900ce80cecfd841bb52c2903a12d41b MD5 | raw file
  1#summary A growing list of code patterns and solutions for documenting them
  2#labels Draft
  3
  4= How do I document <some pattern>? =
  5
  6== Prototype Library-Based Classes ==
  7=== Class Pattern ===
  8{{{
  9var MyClass = Class.create(
 10  /** @lends MyClass# */
 11  {
 12    /**
 13     * Description of constructor.
 14     * @class Description of class.
 15     * @constructs
 16     */
 17    initialize: function(arg0, arg1) {
 18      //...
 19    },
 20
 21    /** A method. */
 22    myFunc: function() {},
 23    
 24    /** An instance field. */
 25    myVar: 123
 26  }
 27);
 28
 29// ... and if you want to add class fields ...
 30
 31Object.extend(MyClass,
 32  /** @lends MyClass */
 33  {
 34    /** A class method. */
 35    classFunc: function() {}
 36  }
 37);
 38}}}
 39
 40=== Sub-class Pattern ===
 41{{{
 42/**
 43 * @class
 44 */
 45var MySuper = Class.create(
 46  /** @lends MySuper.prototype */
 47  {
 48    /** A method of the superclass. */
 49    superMethod: function() {
 50      // ...
 51    }
 52});
 53
 54/**
 55 * Class description
 56 * @class
 57 * @augments MySuper
 58 */
 59var MyClass = Class.create(MySuper,
 60  /** @lends MyClass# */
 61  {
 62    /** A method of the  subclass. */
 63    myMethod: function() {
 64      // ...
 65    }
 66  }
 67);
 68
 69}}}
 70
 71=== Mixin Pattern ===
 72{{{
 73// Here's how to define a mixin API
 74/**
 75 * Document Observable class here
 76 * @class
 77 */
 78var Observable =
 79 /**
 80  * This is an API that can be mixed into other objects
 81  * @lends Observable#
 82  */
 83 {
 84  observe: function(callback) {
 85    //...
 86  },
 87  notify: function(event) {
 88    //...
 89  }
 90 };
 91
 92// Now let's mix the API into a class ...
 93
 94/**
 95 * MyClass.prototype gets the Observable API
 96 * @class
 97 * @borrows Observable#observe as #observe
 98 * @borrows Observable#notify as #notify
 99 */
100var MyClass = function() {
101  //...
102}
103MyClass.addMethods(Observable);
104}}}
105
106=== Extends Pattern ===
107This is similar to the Mixin pattern, except it operates on individual instances of objects, not classes
108{{{
109var Slideable = 
110/** @lends Slideable */
111{
112  /**
113    @class API for enabling a "slide" effect on a DOM element
114    @constructs
115  */
116  extend: function(anElement) {
117    Object.extend(anElement, this._methods);
118  },
119
120  
121  _methods: 
122  /** @lends Slideable# */
123  {
124    /** Start the slide. */
125    startSlide: function() {
126    },
127    /** Stop the slide. */
128    stopSlide: function() {
129    },
130  }
131}
132
133
134// Now Make an element slideable
135Slideable.extend(document.getElementById('slider'));
136}}}