Merge pull request #335 from ember-learn/fancier-function-signatures

Support fancier function signatures

Author: dfreeman

addon/components/api/x-section/template.hbs

@@ -1,4 +1,4 @@
-<div data-test-item>
+<div data-test-item class="docs-pb-8">
   <h3
     id={{item.name}}
     data-text="{{item.name}}"

addon/helpers/type-signature.js

@@ -6,14 +6,27 @@ function escape(text) {
   return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-function functionSignature({ name, params, returns }) {
-  let paramSignature = params.filter(p => !p.name.includes('.')).map(({ name, type }) => {
-    return [`<strong>${name}</strong>`, `<em>${type}</em>`].join(': ');
-  }).join(', ')
+function functionSignature(fn) {
+  // Functions may have { params, typeParams, returns } directly on them, or they
+  // may have a `signatures` array of hashes each with those properties.
+  let signatures = (fn.signatures || [fn]).map(({ params, typeParams, returns }) => {
+    let paramSignature = params.filter(p => !p.name.includes('.')).map(({ name, type, isRest, isOptional }) => {
+      let prefix = isRest ? '...' : '';
+      let suffix = isOptional ? '?' : '';
+      return `${prefix}<strong>${name}</strong>${suffix}: <em>${type}</em>`;
+    }).join(', ');
 
-  let returnType = returns ? returns.type : 'any';
+    let typeParamSignature = '';
+    if (typeParams && typeParams.length) {
+      typeParamSignature = `&lt;${typeParams.map(p => `<em>${p}</em>`).join(', ')}&gt;`;
+    }
 
-  return `<strong>${name}</strong>(${paramSignature}): <em>${returnType}</em>`;
+    let returnType = returns ? returns.type : 'any';
+
+    return `<strong>${fn.name}</strong>${typeParamSignature}(${paramSignature}): <em>${returnType}</em>`;
+  });
+
+  return signatures.join('<br>');
 }
 
 function accessorSignature({ name, type, hasGetter, hasSetter }) {

addon/utils/compile-markdown.js

@@ -11,15 +11,21 @@ import json from 'highlight.js/lib/languages/json';
 import xml from 'highlight.js/lib/languages/xml';
 import diff from 'highlight.js/lib/languages/diff';
 import shell from 'highlight.js/lib/languages/shell';
+import typescript from 'highlight.js/lib/languages/typescript';
 
 hljs.registerLanguage('javascript', javascript);
+hljs.registerLanguage('js', javascript);
 hljs.registerLanguage('css', css);
 hljs.registerLanguage('handlebars', handlebars);
 hljs.registerLanguage('htmlbars', htmlbars);
+hljs.registerLanguage('hbs', htmlbars);
 hljs.registerLanguage('json', json);
 hljs.registerLanguage('xml', xml);
 hljs.registerLanguage('diff', diff);
 hljs.registerLanguage('shell', shell);
+hljs.registerLanguage('sh', shell);
+hljs.registerLanguage('typescript', typescript);
+hljs.registerLanguage('ts', typescript);
 
 function highlightCode(code, lang) {
   return hljs.getLanguage(lang) ? hljs.highlight(lang, code).value : code

lib/utils/compile-doc-descriptions.js

@@ -0,0 +1,118 @@
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'ember-qunit';
+import { render } from '@ember/test-helpers';
+import hbs from 'htmlbars-inline-precompile';
+
+module('Integration | Helpers | type-signature', function(hooks) {
+  setupRenderingTest(hooks);
+
+  test('renders a simple getter signature', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      hasGetter: true,
+      type: 'string'
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'get foo: string');
+  });
+
+  test('renders a simple setter signature', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      hasSetter: true,
+      type: 'string'
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'set foo: string');
+  });
+
+  test('renders a simple getter signature', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      hasGetter: true,
+      hasSetter: true,
+      type: 'string'
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'get/set foo: string');
+  });
+
+  test('renders a simple variable', async function(assert) {
+    this.set('item', { name: 'foo', type: 'string' });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'foo: string');
+  });
+
+  test('renders a simple function signature', async function(assert) {
+    this.set('item', { name: 'foo', params: [], returns: { type: 'string' } });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'foo(): string');
+  });
+
+  test('renders static and access modifiers', async function(assert) {
+    this.set('item', { name: 'foo', type: 'string', isStatic: true, access: 'private' });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'private static foo: string');
+  });
+
+  test('renders functions with optional and rest params', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      params: [
+        { name: 'a', type: 'number' },
+        { name: 'b', type: 'string', isOptional: true },
+        { name: 'c', type: 'any[]', isRest: true }
+      ]
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'foo(a: number, b?: string, ...c: any[]): any');
+  });
+
+  test('renders functions with type params', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      typeParams: ['T, U extends PromiseLike<T>'],
+      params: [{ name: 'value', type: 'U' }],
+      returns: { type: 'T' },
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'foo<T, U extends PromiseLike<T>>(value: U): T');
+  });
+
+  test('renders functions with multiple signatures', async function(assert) {
+    this.set('item', {
+      name: 'foo',
+      signatures: [
+        {
+          params: [],
+          returns: { type: 'Promise&lt;void&gt;' }
+        },
+        {
+          typeParams: ['T'],
+          params: [{ name: 'value', type: 'T' }],
+          returns: { type: 'Promise&lt;T&gt;' }
+        }
+      ]
+    });
+
+    await render(hbs`{{type-signature item}}`);
+
+    assert.equal(this.element.innerText, 'foo(): Promise<void>\nfoo<T>(value: T): Promise<T>');
+  });
+});