Converted ember-routing docs

Author: wagenet

packages/ember-routing/lib/location/api.js

@@ -1,6 +1,11 @@
+/**
+@module ember
+@submodule ember-routing
+*/
+
 var get = Ember.get, set = Ember.set;
 
-/**
+/*
   This file implements the `location` API used by Ember's router.
 
   That API is:
@@ -12,17 +17,19 @@ var get = Ember.get, set = Ember.set;
 
   Calling setURL will not trigger onUpdateURL callbacks.
 
-  TODO: This, as well as the Ember.Location documentation below, should
-  perhaps be moved so that it's visible in the JsDoc output.
+  TODO: This should perhaps be moved so that it's visible in the doc output.
 */
-/**
-  @class
 
+/**
   Ember.Location returns an instance of the correct implementation of
   the `location` API.
 
   You can pass it a `implementation` ('hash', 'history', 'none') to force a
   particular implementation.
+
+  @class Location
+  @namespace Ember
+  @static
 */
 Ember.Location = {
   create: function(options) {

packages/ember-routing/lib/location/hash_location.js

@@ -1,18 +1,21 @@
+/**
+@module ember
+@submodule ember-routing
+*/
+
 var get = Ember.get, set = Ember.set;
 
 /**
-  @class
-
   Ember.HashLocation implements the location API using the browser's
   hash. At present, it relies on a hashchange event existing in the
   browser.
 
+  @class HashLocation
+  @namespace Ember
   @extends Ember.Object
 */
-Ember.HashLocation = Ember.Object.extend(
-/** @scope Ember.HashLocation.prototype */ {
+Ember.HashLocation = Ember.Object.extend({
 
-  /** @private */
   init: function() {
     set(this, 'location', get(this, 'location') || window.location);
   },
@@ -21,6 +24,8 @@ Ember.HashLocation = Ember.Object.extend(
     @private
 
     Returns the current `location.hash`, minus the '#' at the front.
+
+    @method getURL
   */
   getURL: function() {
     return get(this, 'location').hash.substr(1);
@@ -32,6 +37,9 @@ Ember.HashLocation = Ember.Object.extend(
     Set the `location.hash` and remembers what was set. This prevents
     `onUpdateURL` callbacks from triggering when the hash was set by
     `HashLocation`.
+
+    @method setURL
+    @param path {String}
   */
   setURL: function(path) {
     get(this, 'location').hash = path;
@@ -44,6 +52,9 @@ Ember.HashLocation = Ember.Object.extend(
     Register a callback to be invoked when the hash changes. These
     callbacks will execute when the user presses the back or forward
     button, but not after `setURL` is invoked.
+
+    @method onUpdateURL
+    @param callback {Function}
   */
   onUpdateURL: function(callback) {
     var self = this;
@@ -67,12 +78,14 @@ Ember.HashLocation = Ember.Object.extend(
 
     This is used, for example, when using the {{action}} helper
     to generate a URL based on an event.
+
+    @method formatURL
+    @param url {String}
   */
   formatURL: function(url) {
     return '#'+url;
   },
 
-  /** @private */
   willDestroy: function() {
     var guid = Ember.guidFor(this);
 

packages/ember-routing/lib/location/history_location.js

@@ -1,38 +1,49 @@
+/**
+@module ember
+@submodule ember-routing
+*/
+
 var get = Ember.get, set = Ember.set;
 
 /**
-  @class
-
   Ember.HistoryLocation implements the location API using the browser's
   history.pushState API.
 
+  @class HistoryLocation
+  @namespace Ember
   @extends Ember.Object
 */
-Ember.HistoryLocation = Ember.Object.extend(
-/** @scope Ember.HistoryLocation.prototype */ {
+Ember.HistoryLocation = Ember.Object.extend({
 
-  /** @private */
   init: function() {
     set(this, 'location', get(this, 'location') || window.location);
     set(this, '_initialURL', get(this, 'location').pathname);
   },
 
   /**
     Will be pre-pended to path upon state change
-   */
+
+    @property rootURL
+    @default '/'
+  */
   rootURL: '/',
 
   /**
     @private
 
     Used to give history a starting reference
-   */
+
+    @property _initialURL
+    @default null
+  */
   _initialURL: null,
 
   /**
     @private
 
     Returns the current `location.pathname`.
+
+    @method getURL
   */
   getURL: function() {
     return get(this, 'location').pathname;
@@ -42,6 +53,9 @@ Ember.HistoryLocation = Ember.Object.extend(
     @private
 
     Uses `history.pushState` to update the url without a page reload.
+
+    @method setURL
+    @param path {String}
   */
   setURL: function(path) {
     var state = window.history.state,
@@ -59,6 +73,9 @@ Ember.HistoryLocation = Ember.Object.extend(
 
     Register a callback to be invoked whenever the browser
     history changes, including using forward and back buttons.
+
+    @method onUpdateURL
+    @param callback {Function}
   */
   onUpdateURL: function(callback) {
     var guid = Ember.guidFor(this);
@@ -72,6 +89,9 @@ Ember.HistoryLocation = Ember.Object.extend(
     @private
 
     Used when using {{action}} helper.  The url is always appended to the rootURL.
+
+    @method formatURL
+    @param url {String}
   */
   formatURL: function(url) {
     var rootURL = get(this, 'rootURL');
@@ -83,7 +103,6 @@ Ember.HistoryLocation = Ember.Object.extend(
     return rootURL + url;
   },
 
-  /** @private */
   willDestroy: function() {
     var guid = Ember.guidFor(this);
 

packages/ember-routing/lib/location/none_location.js

@@ -1,17 +1,21 @@
+/**
+@module ember
+@submodule ember-routing
+*/
+
 var get = Ember.get, set = Ember.set;
 
 /**
-  @class
-
   Ember.NoneLocation does not interact with the browser. It is useful for
   testing, or when you need to manage state with your Router, but temporarily
   don't want it to muck with the URL (for example when you embed your
   application in a larger page).
 
+  @class NoneLocation
+  @namespace Ember
   @extends Ember.Object
 */
-Ember.NoneLocation = Ember.Object.extend(
-/** @scope Ember.NoneLocation.prototype */ {
+Ember.NoneLocation = Ember.Object.extend({
   path: '',
 
   getURL: function() {

packages/ember-routing/lib/main.js

@@ -7,3 +7,11 @@
 require('ember-states');
 require('ember-routing/route');
 require('ember-routing/router');
+
+/**
+Ember Routing
+
+@module ember
+@submodule ember-routing
+@requires ember-states
+*/