SproutCore’s build system comes with a built-in reference documentation tool based on JSDoc. You can use it to generate documentation for SproutCore or for your own application. Reference documentation is a great way to help everyone on your team quickly learn how to use the classes you write in their own part of the code.

Why Include Documentation

If you are writing a framework you want to share with the world, inline documentation makes sense. But why write inline docs for code you write in your own application? Well, there are a few of really good reasons:

1. Sharing with your team. Even if it is just you writing an application today, documentation will help make sure that you or anyone else on your team will be able to understand what you wrote later on.
2. Thinking through your code. Documenting your APIs helps you to think through the methods you are writing. What will they do? What parameters must they accept? What must they return? What about error conditions? You simply write better code when you document it as well.
3. Searching your APIs. Best of all, if you use the formatting instructions described here, the documentation you write can be pulled out and used in the SproutCore Documentation View, which includes a built-in symbol search. This can go a long ways towards helping you and others on your team avoid writing duplicate code when you project gets large.

Building and Browsing Documentation

To view the docs for SproutCore, make sure your development server is running and visit http://localhost:4020/sproutcore/-docs. The first time you visit the docs page, no documentation will exist yet because it has not been generated yet. To generate the documentation click “Rebuild Docs” in the lower left corner.

IMPORTANT: SproutCore does not automatically generate documentation for you because it can take a long time to run. Anytime you make changes to your code and you want to see the latest docs, click the “Rebuild Docs” button in the Doc Tool.

You can view the documentation for any client or framework you create also by adding “/-docs” to the URL for your client or framework. For example if you load your application at http://localhost:4020/contacts in development mode, you can load the documentation for the client by visiting http://localhost:4020/contacts/-docs.

The first time you visit the doc tool for a client, click the “Rebuild Docs” button in the lower left corner. Anytime you have updated your code and want to see your latest changes, just click the “Rebuild Docs” button again to get new code.

Writing Your Own Docs

SproutCore’s Doc Tool is based on the open source JSDoc Toolkit. To get the tool to recognize your documentation, you need to follow the conventions in JSDoc. In addition, the SproutCore project has established some best practices to follow when writing your own documentation that will help yield clear, concise documentation.

Documenting Classes

Each class you create should have a description at the top explaining the purpose of the class and how to use it. The SproutCore Generators will automatically create new class templates with places for you to document your classes. Just fill in the spots where needed. Here is what a typical documentation will look like:

  /** <-- Two * are required.  Do not start each line with an asterisk.

  @class  <-- IMPORTANT: must be at the top of your declaration

  v-- Provide a 1 paragraph overview of the class
  A Timer executes a method after a defined period of time.  Timers are
  significantly more efficient than using setTimeout() or setInterval()
  because they are cooperatively scheduled using the run loop.  Timers are
  also gauranteed to fire at the same time, making it far easier to keep
  multiple timers in sync.      

  v-- Add a section for each major task someone might perform with your class
  h2. Scheduling a Timer  <-- Use Textile to format text. Headings are h2.

  To schedule a basic timer, you can simply call SC.Timer.schedule() with
  a target and action you wish to have invoked:      

  {{{ <-- Wrap code examples in {{{ ... }}}
     var timer = SC.Timer.schedule({
       target: myObject, action: 'timerFired', interval: 100
     });
  }}}

  When this timer fires, it will call the timerFired() method on myObject.
  In addition to calling a method on a particular object, you can also use
  a timer to execute a variety of other types of code:

  v-- Use - for bulleted lists
  - If you do not pass a target object, then the action method will be passed,
    down the responder chain.
  - If you pass a string with a period in it for the action, it will be treated
    as a property path.
  - If you pass a function for the action, the function will be called in the
    content of the target.

  @extends SC.Object  <-- Add an @extends for each class or mixin you import
  @author Charles Jolley <-- Your name goes here
  @version 1.0
  @since version 1.0  <-- Can be omitted, but useful for frameworks
*/
SC.Timer = SC.Object.extend(
/** @scope SC.Timer.prototype */ { <-- IMPORTANT: @scope required
...
});

Documenting Properties

Properties are static values or computed properties that should be accessed using get() and set() on your method. These properties will appear in your documentation in the Fields section of the page. This is how you should write property documentation:

  /** <-- Two * are required.  Do not start each line with an asterisk.

    v-- One sentence summary.  Appears in tooltip and at the top of a field
        description.
    The target object whose method will be invoked when the time fires.

    v-- Add any extended discussion with more details of the property in a
        separate paragraph.  This will appear in the "Discussion" section of
        the docs.
    You can set either a target/action property or you can pass a specific
    method.

    @type {Object} <-- Specify the type of objects that belong in the field.
    @field <-- IMPORTANT: Required by JSDoc
  */
  target: null,

Properties beginning with an underscore will not appear in the documentation since they are private properties.

NOTE: The current version of JSDoc included with SproutCore improperly places documentation for computed properties in the Methods section instead of in the fields. This has been fixed for the next release of JSDoc which will be included in SproutCore when it is ready. You should always use the format described above, even for computed properties, so that your code will be ready for the new version of JSDoc.

Documenting Methods

Methods are functions you expect other code to execute specifically or to override. These methods will appear in your documentation in the Methods section of the page. This is how you should write method documentation:

  /** <-- IMPORTANT: Two * are required.  Do not start each line with an asterisk.

    v-- One sentence summary.  Will appear in tooltip and at top of method
      description
    Called whenever the view's innerFrame size changes.  You can override this
    method to perform your own layout of your child views.

    v-- Add any extended discussion here.  Appears in "Discussion" section.
    If you do not override this method, the view will assume you are using
    CSS to layout your child views.  As an optimization the view may not
    always call this method if it determines that you have not overridden it.

    This default version simply calls resizeWithOldParentSize() on all of its
    children.

    v-- One @param line for each param.  Name the property, type, and description
    @param oldSize {Size} The old frame size of the view.
    @returns {void} Nothing. <-- Return type and description.  Always include at least {void}
  */
  resizeChildrenWithOldSize: function(oldSize) {
  ...
  },

Methods beginning with an underscore will not appear in the documentation since they are private methods.

Related Links

• JSDoc Toolkit – Documentation for the documentation engine that powers the SproutCore Doc Tools

Comments

Lawrence: Wrapping code examples in {{{ … }}} doesn’t render nicely. It loses all indentation.