Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
142 lines (92 sloc) 5.3 KB

SproutCore 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.

endprologue.

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.

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.

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 (-)

/**
@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 Firebug Logging Reference @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.

Note: 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.

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.

/**
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) {},

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.

/**
@class

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

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

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.

/**
Description

@default YES @type Boolean

*/
isAsynchronous: YES,

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

Computed Properties

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

/**
Description

@field @default YES @type Boolean

*/
isAsynchronous: function(){…

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 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.

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

References

Changelog

  • March 22, 2011: initial version by Majd Taby
Something went wrong with that request. Please try again.