Documentation Guidelines

This guide will walk you through writing documentation for your SproutCore classes in a format that is friendly to jsdoc-toolkit, the library used for generating documentation from code.

1 - Overview

SproutCore uses the jsdoc-toolkit to generate its documentation. As such, your SproutCore classes should follow strict code-documenting formatting guidelines in order to properly generate your HTML documentation. This document outlines the proper format you should use.

2 - Classes

Classes must always start with an @class directive, followed by optional the class description. You can use Markdown to style your description (add headings, paragraphs, code, etc.)

JsDoc Toolkit also supports tags in your comments to add metadata about your class. For example, you can specify who the author of the class is, what classes it inherits from, what classes are related, and what version of the frameworks it’s been available since.

2.1 - Common and Supported Markdown Syntax

For code samples, make sure you indent the code block further than the other text
For headers, add three dashes (---) for 2nd level headers, and three (===) for 1st level headers. These go on the subsequent line
For list, prefix each line with a dash (-)

"Sample Class Documentation"
/**
  @class

  Class Description
  ======

  Overview
  ----------

  This is a sample description. Here’s some code:

         SC.Store.find(...)

  And here’s a list:

  - Eggs
  - Butter

  @deprecated This class has been deprecated. Please use SC.NewRequest
  @see <a href="http://getfirebug.com/logging.html">Firebug Logging Reference</a>
  @extends SC.Object
  @author Majd Taby
  @since SproutCore 1.0
*/

SC.Request = SC.Object.extend(
 /** @scope SC.Request.prototype */{
 ...
});

The @scope definition is mandatory, and it defines what class/namespace the proceeding code documents.

You can define multiple @see/extends/author directives for each class, as you see fit.

WARN: You cannot put any javascript between your documentation and the class it’s documenting. Otherwise, JsDoc will get confused by what you’re trying to document.

2.2 - Instance Methods

Documenting methods follows the same general structure as a class, but with a different set of required/optional directives. You start off by describing the method’s functionality, followed by the parameters, and then the return types.

It’s important to keep in mind that the jsdoc toolkit does not parse javascript code. This means that you need to put the name of the parameters in the documentation, and it’s your responsibility to keep them up to date as you update the method.

In the example below, the response property is marked as optional by wrapping the name in square brackets.

"Sample Instance Method Documentation"
/**
  Method description.

  @param {SC.Request}   request     A copy of the request, frozen.
  @param {SC.Response} [response]   An optional parameter
  @param {SC.Response} [foobar]     A sample parameter

  @throws {SC.Exception} SC.RequestNotValidException
  @returns {Boolean} Yes on success, NO on failure.
*/
didSend: function(request, response) {},

2.3 - Class Methods

Class methods are usually implemented by mixing-in extra methods to an existing class. For these methods/properties to show up in the same location in the generated output, you need to add a @scope declaration just as you did with the class.

"Sample Class Method Documentation"
/**
  @class

   ...
*/
SC.Store = SC.Object.extend(/** @scope SC.Store.prototype */{...});

SC.Store.mixin(/** @scope SC.Store.prototype */{...})

2.4 - Properties

Properties are arguably the simplest entity to document. You simply need to write a description of what the property represents, and what type it is. You can optionally provide a default value.

"Sample Property Documentation"
/**
  Description

  @default YES
  @type Boolean
*/
isAsynchronous: YES,

Constants are documented using @constant but they don’t need a default value.

2.5 - Computed Properties

Computed Properties are documented just like regular properties but they add the @field property.

"Sample Computed Property Documentation"
/**
  Description

  @field
  @default YES
  @type Boolean
*/
isAsynchronous: function(){...

3 - Testing and viewing your documentation during development

If, during development, you would like to test your documentation and see how it looks once it's generated, then you can use the SproutCore TextMate bundle available on "github":https://github.com/sproutcore/sproutcore-tmbundle which includes a Command to generate documentation for the current file you are viewing. To activate it, go to a jsdoc-documented javascript file, and click CMD CTRL G.

Generating documentation in TextMate requires the Web Sharing feature of Mac OS X to be enabled since it uses apache to display your files.

3.1 - References

JSDoc Tag Reference

4 - Changelog

March 22, 2011: initial version by Majd Taby
August 14, 2013: converted to Markdown format for DocPad guides by Topher Fangio

SproutCore Guides