From 40b63fab19a8c86f7e446b61b31bc7b4324aee9a Mon Sep 17 00:00:00 2001
From: Matthew Beale <matt.beale@madhatted.com>
Date: Wed, 4 Nov 2015 23:08:42 -0500
Subject: [PATCH] Document getOwner and setOwner

---
 packages/container/lib/owner.js | 55 +++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/packages/container/lib/owner.js b/packages/container/lib/owner.js
index 71d0b7b0acb..7800dae55d7 100644
--- a/packages/container/lib/owner.js
+++ b/packages/container/lib/owner.js
@@ -1,11 +1,66 @@
+/**
+@module ember
+@submodule ember-runtime
+*/
+
 import { symbol } from 'ember-metal/utils';
 
 export const OWNER = symbol('OWNER');
 
+
+/**
+  Framework objects in an Ember application (components, services, routes, etc.)
+  are created via a factory and dependency injection system. Each of these
+  objects is the responsibility of an "owner", which handled its
+  instantiation and manages its lifetime.
+
+  `getOwner` fetches the owner object responsible for an instance. This can
+  be used to lookup or resolve other class instances, or register new factories
+  into the owner.
+
+  For example, this component dynamically looks up a service based on the
+  `audioType` passed as an attribute:
+
+  ```
+  // app/components/play-audio.js
+  import Ember from 'ember';
+
+  // Usage:
+  //
+  //   {{play-audio audioType=model.audioType audioFile=model.file}}
+  //
+  export default Ember.Component.extend({
+    audioService: Ember.computed('audioType', function() {
+      let owner = Ember.getOwner(this);
+      return owner.lookup(`service:${this.get('audioType')}`);
+    }),
+    click() {
+      let player = this.get('audioService');
+      player.play(this.get('audioFile'));
+    }
+  });
+  ```
+
+  @method getOwner
+  @param {Object} object A object with an owner.
+  @return {Object} an owner object.
+  @for Ember
+  @public
+*/
 export function getOwner(object) {
   return object[OWNER];
 }
 
+/**
+  `setOwner` forces a new owner on a given object instance. This is primarily
+  useful in some testing cases.
+
+  @method setOwner
+  @param {Object} object A object with an owner.
+  @return {Object} an owner object.
+  @for Ember
+  @public
+*/
 export function setOwner(object, owner) {
   object[OWNER] = owner;
 }