Documentation Conventions

Here’s the skinny on how the SproutCore framework is documented. If you notice a file that doesn’t quite meet these conventions, please feel free to document in this style and contribute the changes. We welcome help with bringing all of the documentation in the framework up to date.

We’ve adopted these conventions to make it faster and easier to accept and merge contributions, to improve the overall quality of our documentation, and to make it easier for everyone work together. After all, who knows what the author of a particular passage of code was thinking when it was developed, or how it’s intended to be used, than that author, right then? To that end, we request that contributions be documented in this manner, to help make everyone’s lives easier and days brighter!

Everywhere

In all comments, there can be multiple authors. If you’ve contributed to a particular piece of code, don’t be shy…we think you should get credit for your work.

Licensing

All files that are a part of the official project should contain a reference to lib/license.js This is critical because it makes it far easier to propagate any licensing changes across the entire project. If you create a framework or other derivative project and have a README file, please be sure to include the following verbiage:

The license for this project is available in the file called license.js located in the lib 
directory of this project.  Please review it carefully before you submit code, as all 
submissions to this project are released under it.

File Headers – Adding a File

Please be absolutely sure you put the header below at the top of every new file. It makes it a lot easier to figure out what we’re looking at when we’re knee-deep in code. In addition to that, we run documentation tests before anything is merged, and they will fail if you don’t do this exactly as specified below.

Filename:

This field must contain the path relative to the framework’s root. In the example below, the file is in the lib directory and you would fill in {CLASSNAME} with the name of the class represented by the file.

Authors:

This field must YOUR name and a permanent email address. Be sure to change the address if your address changes, so that we can find you if we need to communicate with you. If you can’t be found, the copyright to the code will need to be assigned back to the project for safekeeping. The names there are for example purposes only and don’t need to be there unless you’re borrowing some code we wrote or are just THAT immensely grateful, though it has been rumored that some of us may prefer beer for your gratitude instead. Just saying.

Changed:

This field must contain $Version$ when you create it. If you forget or change this, your contribution will not be merged in a timely manner, because there will be problems when we run tests against it.

Since:

This field must contain $Version$ when you create it. If you forget or change this, your contribution will not be merged in a timely manner, because there will be problems when we run tests against it. Furthermore, once the code has been committed, the value it is replaced with can never be changed, otherwise your code will fail those tests we run. Do you sense a pattern here?

Copyright:

You must complete the {YEAR} and {OWNER} fields with the appropriate information (the year the code was written and the entity – that’s a person or organization – that owns the copyright on it). As always, if you don’t do it, your code can’t be committed.

License:

This line must be exactly as it is in the sample if you want your code to be committed.

Example Headers – Adding a File

JavaScript (.js)

/*  ==============================================================================
    Filename:   lib/{CLASSNAME}.js
    Authors:    Charles Jolley (charles@sproutit.com)
                Erich Ocean (erich@atlasocean.com)
                Jonathan Mischo (jmischo@quagility.com)
    Changed:    $Version$
    Since:      $Version$
    Copyright:  Copyright (c){YEAR}  {OWNER}  All rights reserved.
    License:    The license terms for this framework are contained in:
                lib/license.js
    ==============================================================================  */

Parsed HTML Templates (.rhtml)

<!--==============================================================================
    Filename:   english.lproj/blah.rhtml
    Authors:    Charles Jolley (charles@sproutit.com)
                Erich Ocean (erich@atlasocean.com)
                Jonathan Mischo (jmischo@quagility.com)
    Changed:    $Version$
    Since:      $Version$
    Copyright:  Copyright (c){YEAR}  {OWNER}  All rights reserved.
    License:    The license terms for this framework are contained in:
                lib/license.js
    ==============================================================================-->

jsDoc Extensions

We’ve extended jsDoc with a plugin that meets our documentation purposes. This makes it much easier to have intelligible documentation, so we decided to put a handy little quick reference in here, so you can see what our custom tags are.

@summary

A short (1-2 line) summary of what the item does or is for. We do mean short – the @description field is appropriate for the actual description.

@method

This is mostly an alias for @function, since the framework is object-oriented and thus the proper terminology for routines on objects is “method”.

@property

This is an alias for @field. Use @property for both instance variables and computed properties, i.e. functions that end with .property().

@singleton

This is an alias for @class. Please use it for singleton classes, to help keep documentation concise.

@delegate

This is an alias for @namespace. Use this to identify methods that delegates are expected to implement. This helps keep interfaces clearly documented.

@mixin

This is an alias for @namespace. Use this to identify mixins This helps keep things organized and identify to developers how to use a particular piece of code.

@note

This is for a side comment, often about behavior, that doesn’t really fit in the description, or isn’t really necessary in the description.

@comment

This is where to put things along the lines of, “Gee, this widget really should wobble more. We need to do that soon!”

Classes

Classes can extend more than one other class, as such, there can be multiple @extends tags. The same applies to properties, as what use is a class structure if classes can only have a single property? You can add as many @property tags as you need.

/**
  @class
  @extends 
      .
      .
      .
  @since
  @version

  @author Charles Jolley (charles@sproutit.com)
      .
      .
      .

  @summary

  @description

  @example

  @property
      .
      .
      .
*/

Methods

Methods take parameters (or arguments, if you feel like arguing), so it makes sense that you’d sometimes (often) have more than one @param to list. Please don’t forget to list them all.

/**
  @method
  @since
  @version

  @author Erich Ocean (erich@atlasocean.com)
      .
      .
      .

  @summary

  @description

  @example

  @param 
      .
      .
      .
  @return 
  @throws
*/

Properties

/**
  @property
  @since
  @version

  @author Jonathan Mischo (jmischo@quagility.com)
      .
      .
      .

  @summary

  @description

  @example

  @type
*/