##Docs Audit Postmortem
In preparation for the Ember.js 1.0 release we performed a documentation audit of the YUIDoc-formatted inline API documentation that becomes the text of http://emberjs.com/api/.
The goal of this audit was three-fold:
- verify each documented API for correctness
- add documentation to public APIs that were undocumented
- update examples that are no longer considered best practices
Despite what you may have read on Hacker News, Ember has really solid documentation coverage. Excluding tests and external dependencies we vendor a run of cloc . --exclude-dir=tests,loader,metamorph,rsvp,vendor shows a 1:1.2 documentation:code ratio just in API docs. The Ember Guides push this a bit higher.
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Javascript 151 6107 13656 11332
-------------------------------------------------------------------------------
SUM: 151 6107 13656 11332
-------------------------------------------------------------------------------The audit ran for a month and involved 13 authors: @sdhull @trek @cavneb @chadhietala @twokul @jdjkelly @bmac @fivetanley @rjackson @heyjinkim @andremalan @eccegordo @oskarols scouring every line of documentation. We ended up with 1,733 additional lines of documentation.
Of the 13 contributors, 8 were first time contributors to Ember.js: @sdhull @cavneb @bmac @rjackson @heyjinkim @andremalan @eccegordo @oskarols Additionally, @oskarols's commit was his first commit to github ever.
Some of the previously undocumented methods, properties, and events that are now documented:
- Controller#controllers
- Application#advanceReadiness
- Resolver#lookupDescription
- SelectView#disabled
- TextField#insertNewLine
- TextField#keyPress
- {{each}} with groupedRows (experimental)
- Ember.computed.empty
- Ember.computed.NotEmpty
- Ember.computed.none
- Ember.computed.not
- Ember.computed.bool
- Ember.computed.match
- Ember.computed.equal
- Ember.computed.gt
- Ember.computed.gte
- Ember.computed.lt
- Ember.computed.lte
- Ember.computed.and
- Ember.computed.or
- Ember.computed.any
- Ember.computed.map
- Ember.computed.defaulTo
- Ember.Logger.log
- Ember.Logger.warn
- Ember.Logger.error
- Ember.Logger.info
- Ember.Logger.debug
- Ember.Logger.assert
- Ember.merge
- Ember.Instrumentation
- Ember.setProperties
- Ember.set
- Ember.tryInvoke
- Controller#transitionToRoute
- View#connectOutlet
- View#disconnectOutlet
- {{control}} (experimental)
- LinkView#attributeBindings
- LinkView#classNameBindings
- LinkView#loading
- Ember.Location
- Route#send
- Route#generateController
- Route#modelFor
- Route#setupController
- Route#replaceWith
- Route#transitionTo
- Object.reopen
- Object.reopenClass
- State and StateManager (which are being moved into an addon)
- The ember-testing package
- CollectionView#destroy
- CollectionView#arrayWillChange
- CollectionView#createChildView
- Ember.CoreView
Finally, two large overall changes that improved the correctness of examples:
- globals for bound property examples were removed in favor of controller lookup
- unquoted handlebars arguments (which soon will be lookups) were changed to being quoted.
There's still a small amount of undocumented areas, but these are either deeply internal or have guide coverage. If you're looking to contribute, we always welcome contributors to find undocumented areas, learn what they do, and submit a PR.