From 1506d79f3b0ff650573a8ff5d31158f27eff83a9 Mon Sep 17 00:00:00 2001
From: Sergio Arbeo <serabe@gmail.com>
Date: Fri, 5 Aug 2016 20:06:53 +0200
Subject: [PATCH] [DOC release] Extend `Route.paramsFor` documentation

Improve documentation on `Route.paramsFor`.

Fixes #13771
---
 packages/ember-routing/lib/system/route.js | 36 ++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/packages/ember-routing/lib/system/route.js b/packages/ember-routing/lib/system/route.js
index 9a282b57735..6ae295b65b3 100644
--- a/packages/ember-routing/lib/system/route.js
+++ b/packages/ember-routing/lib/system/route.js
@@ -344,11 +344,43 @@ let Route = EmberObject.extend(ActionHandler, Evented, {
   mergedProperties: ['queryParams'],
 
   /**
-    Retrieves parameters, for current route using the state.params
-    variable and getQueryParamsFor, using the supplied routeName.
+    Returns a hash containing the parameters of an ancestor route.
+
+    Example
+
+    ```javascript
+    App.Router.map(function() {
+      this.route('member', { path: ':name' }, function() {
+        this.route('interest', { path: ':interest' });
+      });
+    });
+
+    App.MemberRoute = Ember.Route.extend({
+      queryParams: {
+        memberQp: { refreshModel: true }
+      }
+    });
+
+    App.MemberInterestRoute = Ember.Route.extend({
+      queryParams: {
+        interestQp: { refreshModel: true }
+      },
+
+      model() {
+        return this.paramsFor('member');
+      }
+    });
+    ```
+
+    If we visit `/turing/maths?memberQp=member&interestQp=interest` the model for
+    the `member.interest` route is hash with:
+
+    * `name`: `turing`
+    * `memberQp`: `member`
 
     @method paramsFor
     @param {String} name
+    @return {Object} hash containing the parameters of the route `name`
     @public
   */
   paramsFor(name) {