emberjs/data — pull request #890 by thomasboyt (2013-04-16 01:59:16+00:00)
Title: Better YUIDocs

This giant commit is a first pass at generating API documentation from Ember Data. It does the following:

* Turns the various documentation comment blocks in Ember Data into valid YUIDoc comments, just like those found in Ember.js, by adding `@method` and `@class` declarations.
* Creates various YUIDoc modules.
* Adds more documentation to `DS.Model` and `DS.Store` (first pass at events and the main API methods).

This does not add a built version of the documentation to the repository, nor a `rake` task to build it. Right now, it can simply be built by running `yuidoc` in the `doc/` folder, which will output static API documentation to `doc/build`.

Example documentation generated with `yuidoc` can be found [here](http://dl.dropboxusercontent.com/u/80097157/ember-data/index.html).

I know that Ember Data is constantly in flux, and that writing a proper guide to writing adapters and serializers for it right now would be an exercise in futility with the various breaking revisions. But with the surprisingly copious documentation already available in the source, it would be good to at least put out generated API documentation for the current version of Ember Data, so that the source would not be the only reference.

Regardless of what the final documentation looks like - I'd imagine it would be built with a process similar to the Ember website's - these comments will certainly be used in them. Even if an official API documentation site is a ways off, this is a good starting point on that road, and will hopefully lead to more documentation improvements down the line.