feat: show method params and return type (#147)

Author: web-padawan

.changeset/fast-candles-beam.md

@@ -0,0 +1,5 @@
+---
+'@api-viewer/docs': patch
+---
+
+Show method params and return type

docs/assets/custom-elements.json

@@ -690,6 +690,32 @@
               "attribute": "indeterminate",
               "reflects": true
             },
+            {
+              "kind": "method",
+              "name": "setBounds",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "min",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "minimum value"
+                },
+                {
+                  "name": "max",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "maximum value"
+                }
+              ],
+              "description": "Set both minimum and maximum value."
+            },
             {
               "kind": "method",
               "name": "_normalizedValueChanged",

docs/docs/api/styling.md

@@ -6,7 +6,7 @@ The following custom CSS properties are available:
 
 | Property                         | Description                                     |
 | -------------------------------- | ----------------------------------------------- |
-| `--ave-accent-color`             | Accent color, used for property names           |
+| `--ave-accent-color`             | Accent color, used for property / method names  |
 | `--ave-border-color`             | Color used for borders and dividers             |
 | `--ave-border-radius`            | Border radius used for the outer border         |
 | `--ave-button-active-background` | Color of the `:focus` and `:hover` button       |
@@ -20,6 +20,7 @@ The following custom CSS properties are available:
 | `--ave-link-hover-color`         | API description links hover color               |
 | `--ave-monospace-font`           | Monospace font stack for the API items          |
 | `--ave-primary-color`            | Primary color, used for header and active tab   |
+| `--ave-secondary-color`          | Color used for method types in API docs         |
 | `--ave-tab-color`                | Inactive tabs color                             |
 | `--ave-tab-selected-color`       | Selected tab color                              |
 | `--ave-tab-indicator-size`       | Size of the selected tab indicator              |
@@ -47,9 +48,15 @@ The following CSS shadow parts are available:
 | `docs-column`            | Column, child of a `docs-row` part                      |
 | `docs-item`              | Item representing a single entry (property, event etc)  |
 | `docs-label`             | Label (name, attribute, type, description)              |
-| `docs-markdown`          | Iem description with parsed markdown content            |
+| `docs-markdown`          | Item description with parsed markdown content           |
+| `docs-method`            | Method name with its params and return type             |
+| `docs-method-params`     | Comma-separated list of method params their types       |
+| `docs-method-type`       | Return type of a method, or "void" if not specified     |
+| `docs-param-name`        | Name of a method parameter                              |
+| `docs-param-type`        | Type of a method parameter                              |
 | `docs-row`               | Row containing columns. Child of a `docs-item` part     |
 | `docs-value`             | Sibling of a `docs-label` part (name, attribute, type)  |
+| `docs-value`             | Sibling of a `docs-label` part (name, attribute, type)  |
 | `md-h1`                  | Markdown `<h1>` elements                                |
 | `md-h2`                  | Markdown `<h2>` elements                                |
 | `md-h3`                  | Markdown `<h3>` elements                                |

fixtures/lit/src/progress-bar.ts

@@ -182,6 +182,17 @@ export class ProgressBar extends LitElement {
     }
   }
 
+  /**
+   * Set both minimum and maximum value.
+   *
+   * @param {number} min minimum value
+   * @param {number} max maximum value
+   */
+  setBounds(min: number, max: number): void {
+    this.min = min;
+    this.max = max;
+  }
+
   private _normalizedValueChanged(
     value: number,
     min: number,

packages/api-common/src/shared-styles.ts

@@ -14,6 +14,7 @@ export default css`
     border-radius: var(--ave-border-radius);
 
     --ave-primary-color: #01579b;
+    --ave-secondary-color: rgba(0, 0, 0, 0.54);
     --ave-accent-color: #d63200;
     --ave-border-color: rgba(0, 0, 0, 0.12);
     --ave-border-radius: 4px;

packages/api-docs/src/layout.ts

@@ -15,7 +15,7 @@ import { parse } from './utils/markdown.js';
 
 const renderItem = (
   prefix: string,
-  name: string,
+  name: string | TemplateResult,
   description?: string,
   valueType?: string,
   value?: unknown,
@@ -75,6 +75,26 @@ const renderTab = (
   `;
 };
 
+const renderMethod = (method: ClassMethod): TemplateResult => {
+  const params = method.parameters || [];
+  const type = method.return?.type?.text || 'void';
+
+  return html`
+    <span part="docs-method">
+      ${method.name}(<span part="docs-method-params"
+        >${params.map(
+          (param, idx) =>
+            html`<span part="docs-param-name">${param.name}</span>:
+              <span part="docs-param-type">${param.type?.text}</span>${idx ===
+              params.length - 1
+                ? ''
+                : ', '}`
+        )}</span
+      >)</span
+    ><span part="docs-method-type">: ${type}</span>
+  `;
+};
+
 class ApiDocsLayout extends LitElement {
   @property() name = '';
 
@@ -162,8 +182,8 @@ class ApiDocsLayout extends LitElement {
               'Methods',
               methods,
               html`
-                ${methods.map(({ name, description }) =>
-                  renderItem('method', `${name}()`, description)
+                ${methods.map((method) =>
+                  renderItem('method', renderMethod(method), method.description)
                 )}
               `
             )}

packages/api-docs/src/styles.ts

@@ -86,6 +86,14 @@ export default css`
     margin: 0.5rem 0;
   }
 
+  [part$='params'] {
+    color: var(--ave-item-color);
+  }
+
+  [part$='type'] {
+    color: var(--ave-secondary-color);
+  }
+
   .accent {
     color: var(--ave-accent-color);
   }

packages/api-viewer/package.json

@@ -59,7 +59,7 @@
   "size-limit": [
     {
       "path": "lib/api-viewer.js",
-      "limit": "38.5 KB"
+      "limit": "38.6 KB"
     }
   ]
 }