Merge pull request #1289 from emberjs/more-docs-fixes

Add docs for routing and render helper examples

Author: chriskrycho

API.md

@@ -501,7 +501,7 @@ Find all of the elements matching '.my-selector'.
 findAll('.my-selector');
 ```
 
-Returns **[Element][65]** matched element or null
+Returns **([Element][65] | null)** matched element or null
 
 ### findAll
 
@@ -551,6 +551,20 @@ Navigate the application to the provided URL.
 *   `url` **[string][64]** The URL to visit (e.g. `/posts`)
 *   `options` **[object][72]** app boot options
 
+#### Examples
+
+Visiting the route for post 1.
+
+```javascript
+await visit('/posts/1');
+```
+
+Visiting the route for post 1 while also providing the `rootElement` app boot option.
+
+```javascript
+await visit('/', { rootElement: '#container' });
+```
+
 Returns **[Promise][66]\<void>** resolves when settled
 
 ### currentRouteName
@@ -574,6 +588,14 @@ Renders the provided template and appends it to the DOM.
 *   `templateOrComponent` **(Template | Component)** the component (or template) to render
 *   `options` **RenderOptions** options hash containing engine owner ({ owner: engineOwner })
 
+#### Examples
+
+Render a div element with the class 'container'.
+
+```javascript
+await render(hbs`<div class="container"></div>`);
+```
+
 Returns **[Promise][66]\<void>** resolves when settled
 
 ### clearRender
@@ -883,6 +905,17 @@ element).
 
 *   `context` **TestContext** the context to setup for rendering
 
+#### Examples
+
+Rendering out a paragraph element containing the content 'hello', and then clearing that content via clearRender.
+
+```javascript
+await render(hbs`<p>Hello!</p>`);
+assert.equal(this.element.textContent, 'Hello!', 'has rendered content');
+await clearRender();
+assert.equal(this.element.textContent, '', 'has rendered content');
+```
+
 Returns **[Promise][66]\<RenderingTestContext>** resolves with the context that was setup
 
 ### getApplication
@@ -1241,23 +1274,23 @@ Returns **([Array][70]\<Warning> | [Promise][66]<[Array][70]\<Warning>>)** An ar
 
 [54]: #getdeprecations
 
-[55]: #examples-22
+[55]: #examples-25
 
 [56]: #getdeprecationsduringcallback
 
 [57]: #parameters-29
 
-[58]: #examples-23
+[58]: #examples-26
 
 [59]: #getwarnings
 
-[60]: #examples-24
+[60]: #examples-27
 
 [61]: #getwarningsduringcallback
 
 [62]: #parameters-30
 
-[63]: #examples-25
+[63]: #examples-28
 
 [64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 

addon-test-support/@ember/test-helpers/setup-application-context.ts

@@ -130,6 +130,18 @@ export function setupRouterSettlednessTracking() {
   @param {string} url The URL to visit (e.g. `/posts`)
   @param {object} options app boot options
   @returns {Promise<void>} resolves when settled
+
+  @example
+  <caption>
+    Visiting the route for post 1.
+  </caption>
+  await visit('/posts/1');
+
+  @example
+  <caption>
+    Visiting the route for post 1 while also providing the `rootElement` app boot option.
+  </caption>
+  await visit('/', { rootElement: '#container' });
 */
 export function visit(
   url: string,

addon-test-support/@ember/test-helpers/setup-rendering-context.ts

@@ -91,6 +91,12 @@ export interface RenderOptions {
   @param {Template|Component} templateOrComponent the component (or template) to render
   @param {RenderOptions} options options hash containing engine owner ({ owner: engineOwner })
   @returns {Promise<void>} resolves when settled
+
+  @example
+  <caption>
+    Render a div element with the class 'container'.
+  </caption>
+  await render(hbs`<div class="container"></div>`);
 */
 export function render(
   templateOrComponent: TemplateFactory | ComponentInstance,
@@ -270,6 +276,16 @@ export function clearRender(): Promise<void> {
   @public
   @param {TestContext} context the context to setup for rendering
   @returns {Promise<RenderingTestContext>} resolves with the context that was setup
+
+  @example
+  <caption>
+    Rendering out a paragraph element containing the content 'hello', and then clearing that content via clearRender.
+  </caption>
+
+  await render(hbs`<p>Hello!</p>`);
+  assert.equal(this.element.textContent, 'Hello!', 'has rendered content');
+  await clearRender();
+  assert.equal(this.element.textContent, '', 'has rendered content');
 */
 export default function setupRenderingContext(
   context: TestContext