Merge pull request #15616 from emberjs/document-router-service

[DOC release] Improve documentation for RouterService and mount helper
emberjs · Oct 1, 2017 · 862321f · 862321f
2 parents 04b6f42 + b8e786c
commit 862321f
Show file tree

Hide file tree

Showing 3 changed files with 122 additions and 3 deletions.
diff --git a/packages/ember-glimmer/lib/syntax/mount.js b/packages/ember-glimmer/lib/syntax/mount.js
@@ -27,10 +27,31 @@ function dynamicEngineFor(vm, args, meta) {
   {{mount "ember-chat"}}
   ```
 
-  Currently, the engine name is the only argument that can be passed to
-  `{{mount}}`.
+  Additionally, you can also pass in a `model` argument that will be
+  set as the engines model. This can be an existing object:
+  
+  ```
+  <div>
+    {{mount 'admin' model=userSettings}}
+  </div>
+  ```
+
+  Or an inline `hash`, and you can even pass components:
+
+  ```
+  <div>
+    <h1>Application template!</h1>
+    {{mount 'admin' model=(hash
+        title='Secret Admin'
+        signInButton=(component 'sign-in-button')
+    )}}
+  </div>
+  ```
 
   @method mount
+  @param {String} name Name of the engine to mount.
+  @param {Object} [model] Object that will be set as
+                          the model of the engine.
   @for Ember.Templates.helpers
   @category ember-application-engines
   @public

diff --git a/packages/ember-routing/lib/services/router.js b/packages/ember-routing/lib/services/router.js
@@ -18,9 +18,107 @@ import { shallowEqual } from '../utils';
    @category ember-routing-router-service
  */
 const RouterService = Service.extend({
+
+  /**
+     Name of the current route.
+
+     This property represent the logical name of the route,
+     which is comma separated.
+     For the following router:
+
+     ```app/router.js
+     Router.map(function() {
+       this.route('about);
+       this.route('blog', function () {
+         this.route('post', { path: ':post_id' });
+       });
+     });
+     ```
+
+     It will return:
+
+     * `index` when you visit `/`
+     * `about` when you visit `/about`
+     * `blog.index` when you visit `/blog`
+     * `blog.post` when you visit `/blog/some-post-id`
+
+     @property currentRouteName
+     @type String
+     @public
+   */
   currentRouteName: readOnly('_router.currentRouteName'),
+
+  /**
+     Current URL for the application.
+
+    This property represent the URL path for this route.
+    For the following router:
+
+     ```app/router.js
+     Router.map(function() {
+       this.route('about);
+       this.route('blog', function () {
+         this.route('post', { path: ':post_id' });
+       });
+     });
+     ```
+
+     It will return:
+
+     * `/` when you visit `/`
+     * `/about` when you visit `/about`
+     * `/blog/index` when you visit `/blog`
+     * `/blog/post` when you visit `/blog/some-post-id`
+
+     @property currentURL
+     @type String
+     @public
+   */
   currentURL: readOnly('_router.currentURL'),
+
+  /**
+    The `location` property determines the type of URL's that your
+    application will use.
+    The following location types are currently available:
+    * `auto`
+    * `hash`
+    * `history`
+    * `none`
+
+    @property location
+    @default 'hash'
+    @see {Ember.Location}
+    @public
+  */
   location: readOnly('_router.location'),
+
+  /**
+    The `rootURL` property represents the URL of the root of
+    the application, '/' by default.
+    This prefix is assumed on all routes defined on this app.
+
+    IF you change the `rootURL` in your environment configuration
+    like so:
+
+    ```config/environment.js
+    'use strict';
+
+    module.exports = function(environment) {
+      let ENV = {
+        modulePrefix: 'router-service',
+        environment,
+        rootURL: '/my-root',
+      …
+      }
+    ]
+    ```
+
+    This property will return `/my-root`.
+
+    @property rootURL
+    @default '/'
+    @public
+  */
   rootURL: readOnly('_router.rootURL'),
   _router: null,
 

diff --git a/packages/ember-routing/lib/system/router.js b/packages/ember-routing/lib/system/router.js
@@ -73,7 +73,7 @@ const EmberRouter = EmberObject.extend(Evented, {
     * `none` - do not store the Ember URL in the actual browser URL (mainly used for testing)
     * `auto` - use the best option based on browser capabilities: `history` if possible, then `hash` if possible, otherwise `none`
 
-    Note: If using ember-cli, this value is defaulted to `auto` by the `locationType` setting of `/config/environment.js`
+    This value is defaulted to `auto` by the `locationType` setting of `/config/environment.js`
 
     @property location
     @default 'hash'