Documentation Guide

Tyler Keating edited this page Jan 8, 2015 · 3 revisions

SproutCore's documentation is generated using the JSDoc toolkit with a custom template. The following guide explains the proper way to document code so that it results in clean generated docs. All public classes, methods and properties must be documented.

Properties

Required tags

  • @type type - The type of the property. This should be an uppercase primitive: String, Number, Object, Array, Boolean or class: SC.Object, SC.Record, etc.
  • @default value - The default value of the property.
  • @field (computed properties only) - This tag is required with computed properties.

Optional tags

  • @readonly - To indicate that a property should not be set.
  • @deprecated Version version - The version that the property was deprecated. When using deprecated, you can add deprecation notes inside the body of the property description.
  • @since Version version - The version that the property was added. This is useful if a property is later added to an existing class.
  • @see link - Links to other relevant information.

Example

/**
  The first sentence should be a brief description of the property.

  The following paragraphs can add more detail to the property.  Since
  comments are parsed with Markdown, you can add headings with # and ##,
  add examples by indenting 4 spaces and use other Markdown formatting
  to improve the _look_ and **feel** of the documentation.
  
  For example,

      var myObj = MyApp.MyClass.create({
        isValid: false
      });

      myObj.get('thisProp'); // 'fail' <-- 

  @type String
  @default 'fail'
  @see MyApp.MyParentClass#thatProp
  @since Version 1.10
 */
 thisProp: function () {
   return this.get('isValid') ? 'success' : 'fail';
 }.property('isValid')

Methods

Required tags

  • @param {type} name description - The type, name and description of the method's arguments. You can indicate that an argument is optional by enclosing the name in square brackets (ex. [options]) and you can indicate a default value for optional arguments by adding = after the name (ex. [timeout=5]).

Optional tags

  • @returns {type} description - The return type and description of it for the method. This is not required for methods that don't return anything.
  • @deprecated Version version - The version that the method was deprecated. When using deprecated, you can add deprecation notes inside the body of the method description.
  • @since Version version - The version that the method was added. This is useful if a method is later added to an existing class.
  • @see link - Links to other relevant information.

Example

/**
  The first sentence should be a brief description of the method.

  The following paragraphs can add more detail to the method.  Since
  comments are parsed with Markdown, you can add headings with # and ##,
  add examples by indenting 4 spaces and use other Markdown formatting
  to improve the _look_ and **feel** of the documentation.
  
  For example,
      var myOb = MyApp.MyClass.create(),
        x;

      x = myOb.findThings('a', 'm', false);
      // x == Array of objects starting with 'a' and ending with 'm'

  @param {String} firstLetter The first letter that objects should contain.
  @param {String} [secondLetter] The last letter that objects should contain.
  @param {Boolean} [sort=true] Whether the results should be sorted or not.
  @returns {Array} An array of the matching objects constrained by firstLetter and optionally, secondLetter.
  @see MyApp.MyParentClass#similarMethod
  @deprecated Version 1.9
 */
 findThings: function (firstLetter, secondLetter, sort) {
   // ...