Add syntax examples for each tag

pages/tags/alpha.md

@@ -7,6 +7,7 @@ navigation_source: docs_nav
 | Standardization: | [Discretionary]({% link pages/spec/standardization_groups.md %}) |
 | Syntax kind: | [Modifier]({% link pages/spec/tag_kinds.md %}) |
 
+
 ## Suggested meaning
 
 Designates that an API item's release stage is "alpha". It is intended to be used by
@@ -14,9 +15,36 @@ third-party developers eventually, but has not yet been released.  The tooling m
 a public release.
 
 
+## Example
+
+```ts
+/**
+ * Represents a book in the catalog.
+ * @public
+ */
+export class Book {
+  /**
+   * The title of the book.
+   * @alpha
+   */
+  public get title(): string;
+
+  /**
+   * The author of the book.
+   */
+  public get author(): string;
+};
+```
+
+In this example, `Book.author` inherits its `@public` designation from the containing class,
+whereas `Book.title` is marked as "alpha".
+
+
 ## See also
 
 - [@beta]({% link pages/tags/beta.md %}) tag
 - [@experimental]({% link pages/tags/experimental.md %}) tag
-- [@public]({% link pages/tags/public.md %}) tag
 - [@internal]({% link pages/tags/internal.md %}) tag
+- [@public]({% link pages/tags/public.md %}) tag
+- [Trimming based on release tags](https://api-extractor.com/pages/setup/configure_rollup/#trimming-based-on-release-tags):
+  a reference implementation of this feature

pages/tags/beta.md

@@ -17,9 +17,36 @@ change without notice.  The tooling may trim the declaration from a public relea
 developer preview release.
 
 
+## Example
+
+```ts
+/**
+ * Represents a book in the catalog.
+ * @public
+ */
+export class Book {
+  /**
+   * The title of the book.
+   * @beta
+   */
+  public get title(): string;
+
+  /**
+   * The author of the book.
+   */
+  public get author(): string;
+};
+```
+
+In this example, `Book.author` inherits its `@public` designation from the containing class,
+whereas `Book.title` is marked as "beta".
+
+
 ## See also
 
-- [@beta]({% link pages/tags/beta.md %}) tag
+- [@alpha]({% link pages/tags/alpha.md %}) tag
 - [@experimental]({% link pages/tags/experimental.md %}) tag
-- [@public]({% link pages/tags/public.md %}) tag
 - [@internal]({% link pages/tags/internal.md %}) tag
+- [@public]({% link pages/tags/public.md %}) tag
+- [Trimming based on release tags](https://api-extractor.com/pages/setup/configure_rollup/#trimming-based-on-release-tags):
+  a reference implementation of this feature

pages/tags/defaultvalue.md

@@ -12,4 +12,45 @@ navigation_source: docs_nav
 
 This block tag is used to document the default value for a field or property, if a value is not assigned explicitly.
 
-This tag should only be used with fields or properties that are members of a class or interface.
+This tag should only be used with fields or properties that are members of a TypeScript `class` or `interface`.
+
+
+## Example
+
+```ts
+enum WarningStyle {
+  DialogBox,
+  StatusMessage,
+  LogOnly
+}
+
+interface IWarningOptions {
+  /**
+   * Determines how the warning will be displayed.
+   *
+   * @remarks
+   * See {@link WarningStyle| the WarningStyle enum} for more details.
+   *
+   * @defaultValue `WarningStyle.DialogBox`
+   */
+  warningStyle: WarningStyle;
+
+  /**
+   * Whether the warning can interrupt a user's current activity.
+   * @defaultValue
+   * The default is `true` unless
+   *  `WarningStyle.StatusMessage` was requested.
+   */
+  cancellable?: boolean;
+
+  /**
+   * The warning message
+   */
+  message: string;
+}
+```
+
+
+## See also
+
+- [RFC 27](https://github.com/microsoft/tsdoc/issues/27): `@defaultValue` to indicate a default value

pages/tags/deprecated.md

@@ -14,3 +14,21 @@ This block tag communicates that an API item is no longer supported and may be r
 The `@deprecated` tag is followed by a sentence describing the recommended alternative.  It recursively applies
 to members of the container.  For example, if a class is deprecated, then so are all of its members.
 
+
+## Example
+
+```ts
+/**
+ * The base class for controls that can be rendered.
+ *
+ * @deprecated Use the new {@link Control} base class instead.
+ */
+export class VisualControl {
+  . . .
+}
+```
+
+
+## See also
+
+- [Issue 131](https://github.com/microsoft/tsdoc/issues/131): How to deprecate a single parameter

pages/tags/eventproperty.md

@@ -15,3 +15,21 @@ returns an event object that event handlers can be attached to.  The event-handl
 API is implementation-defined, but typically the property return type would be a class
 with members such as `addHandler()` and `removeHandler()`.  A documentation tool can
 display such properties under an "Events" heading instead of the usual "Properties" heading.
+
+
+## Example
+
+```ts
+class MyClass {
+  /**
+    * This event is fired whenever the application navigates to a new page.
+    * @eventProperty
+    */
+  public readonly navigatedEvent: FrameworkEvent<NavigatedEventArgs>;
+}
+```
+
+
+## See also
+
+- [RFC #30](https://github.com/microsoft/tsdoc/issues/30): Marking events using `@eventClass` and/or `@eventProperty`

pages/tags/example.md

@@ -12,3 +12,68 @@ navigation_source: docs_nav
 
 Indicates a documentation section that should be presented as an example illustrating how to use the API.
 It may include a code sample.
+
+Any subsequent text that appears on the same line as the `@example` tag should be interpreted
+as a title for the example.  Otherwise, the documentation tool can index the examples numerically.
+
+## Example A
+
+For this code sample, the generated titles might be **"Example"** and **"Example 2"**:
+
+```ts
+/**
+ * Adds two numbers together.
+ * @example
+ * Here's a simple example:
+ * ```
+ * // Prints "2":
+ * console.log(add(1,1));
+ * ```
+ * @example
+ * Here's an example with negative numbers:
+ * ```
+ * // Prints "0":
+ * console.log(add(1,-1));
+ * ```
+ */
+export function add(x: number, y: number): number {
+}
+```
+
+## Example B
+
+For this code sample, the generated title might be **"Example: Parsing a basic JSON file"**:
+
+```ts
+/**
+ * Parses a JSON file.
+ *
+ * @param path - Full path to the file.
+ * @returns An object containing the JSON data.
+ *
+ * @example Parsing a basic JSON file
+ *
+ * # Contents of `file.json`
+ * ```json
+ * {
+ *   "exampleItem": "text"
+ * }
+ * ```
+ *
+ * # Usage
+ * ```ts
+ * const result = parseFile("file.json");
+ * ```
+ *
+ * # Result
+ * ```ts
+ * {
+ *   exampleItem: 'text',
+ * }
+ * ```
+ */
+ ```
+
+## See also
+
+- [RFC #20](https://github.com/microsoft/tsdoc/issues/20): Syntax for `@example` tag

pages/tags/experimental.md

@@ -8,6 +8,40 @@ navigation_source: docs_nav
 | Syntax kind: | [Modifier]({% link pages/spec/tag_kinds.md %}) |
 | Synonyms: | [@beta]({% link pages/tags/beta.md %}) |
 
+
 ## Suggested meaning
 
 Same semantics as `@beta`, but used by tools that don't support an `@alpha` release stage.
+
+
+## Example
+
+```ts
+/**
+ * Represents a book in the catalog.
+ * @public
+ */
+export class Book {
+  /**
+   * The title of the book.
+   * @experimental
+   */
+  public get title(): string;
+
+  /**
+   * The author of the book.
+   */
+  public get author(): string;
+};
+```
+
+In this example, `Book.author` inherits its `@public` designation from the containing class,
+whereas `Book.title` is marked as "experimental".
+
+
+## See also
+
+- [@alpha]({% link pages/tags/alpha.md %}) tag
+- [@beta]({% link pages/tags/beta.md %}) tag
+- [@public]({% link pages/tags/public.md %}) tag
+- [@internal]({% link pages/tags/internal.md %}) tag

pages/tags/inheritdoc.md

@@ -14,6 +14,10 @@ This inline tag is used to automatically generate an API item's documentation by
 API item.  The inline tag parameter contains a reference to the other item, which may be an unrelated class,
 or even an import from a separate NPM package.
 
+> Note: The notation for declaration references has not been finalized.  See GitHub
+> [issue #9](https://github.com/microsoft/tsdoc/issues/9)
+
+
 ### What gets copied
 
 The `@inheritDoc` tag does not copy the entire comment body. Only the following components are copied:
@@ -27,5 +31,38 @@ The `@inheritDoc` tag does not copy the entire comment body. Only the following
 Other tags such as `@defaultValue` or `@example` are not copied, and need to be explicitly included after
 the `@inheritDoc` tag.
 
-> Note: The notation for API item references has not been finalized.  See GitHub
-> [issue #9](https://github.com/microsoft/tsdoc/issues/9)
+
+## Example
+
+```ts
+import { Serializer } from 'example-library';
+
+/**
+ * An interface describing a widget.
+ * @public
+ */
+export interface IWidget {
+  /**
+   * Draws the widget on the display surface.
+   * @param x - the X position of the widget
+   * @param y - the Y position of the widget
+   */
+  public draw(x: number, y: number): void;
+}
+
+/** @public */
+export class Button implements IWidget {
+  /** {@inheritDoc IWidget.draw} */
+  public draw(x: number, y: number): void {
+    . . .
+  }
+
+  /**
+   * {@inheritDoc example-library#Serializer.writeFile}
+   * @deprecated Use {@link example-library#Serializer.writeFile} instead.
+   */
+  public save(): void {
+    . . .
+  }
+}
+```

pages/tags/internal.md

@@ -15,9 +15,36 @@ declaration from a public release. In some implementations, certain designated p
 consume  internal API items, e.g. because the packages are components of the same product.
 
 
+## Example
+
+```ts
+/**
+ * Represents a book in the catalog.
+ * @public
+ */
+export class Book {
+  /**
+   * The title of the book.
+   * @internal
+   */
+  public get _title(): string;
+
+  /**
+   * The author of the book.
+   */
+  public get author(): string;
+};
+```
+
+In this example, `Book.author` inherits its `@public` designation from the containing class,
+whereas `Book._title` is marked as "internal".
+
+
 ## See also
 
 - [@alpha]({% link pages/tags/alpha.md %}) tag
 - [@beta]({% link pages/tags/beta.md %}) tag
 - [@experimental]({% link pages/tags/experimental.md %}) tag
 - [@public]({% link pages/tags/public.md %}) tag
+- [Trimming based on release tags](https://api-extractor.com/pages/setup/configure_rollup/#trimming-based-on-release-tags):
+  a reference implementation of this feature

pages/tags/label.md

@@ -15,3 +15,42 @@ the TSDoc declaration reference notation.
 
 > Note: The `{@label}` notation has not been finalized.  See GitHub
 > [issue #9](https://github.com/microsoft/tsdoc/issues/9)
+
+
+## Example
+
+```ts
+export interface Interface {
+  /**
+   * Shortest name:  {@link InterfaceL1.(:STRING_INDEXER)}
+   * Full name:      {@link (InterfaceL1:interface).(:STRING_INDEXER)}
+   *
+   * {@label STRING_INDEXER}
+   */
+  [key: string]: number;
+
+  /**
+   * Shortest name:  {@link InterfaceL1.(:NUMBER_INDEXER)}
+   * Full name:      {@link (InterfaceL1:interface).(:NUMBER_INDEXER)}
+   *
+   * {@label NUMBER_INDEXER}
+   */
+  [key: number]: number;
+
+  /**
+   * Shortest name:  {@link InterfaceL1.(:FUNCTOR)}
+   * Full name:      {@link (InterfaceL1:interface).(:FUNCTOR)}
+   *
+   * {@label FUNCTOR}
+   */
+  (source: string, subString: string): boolean;
+
+  /**
+   * Shortest name:  {@link InterfaceL1.(:CONSTRUCTOR)}
+   * Full name:      {@link (InterfaceL1:interface).(:CONSTRUCTOR)}
+   *
+   * {@label CONSTRUCTOR}
+   */
+  new (hour: number, minute: number);
+}
+```

pages/tags/link.md

@@ -14,5 +14,66 @@ The `{@link}` inline tag is used to create hyperlinks to other pages in a
 documentation system or general internet URLs.  In particular, it supports
 expressions for referencing API items.
 
-> Note: The `{@link}` notation has not been finalized.  See GitHub
+> Note: The notation for declaration references has not been finalized.  See GitHub
 > [issue #9](https://github.com/microsoft/tsdoc/issues/9)
+
+## Example
+
+```ts
+/**
+ * Let's learn about the `{@link}` tag.
+ *
+ * @remarks
+ *
+ * Links can point to a URL: {@link https://github.com/microsoft/tsdoc}
+ *
+ * Links can point to an API item: {@link Button}
+ *
+ * You can optionally include custom link text: {@link Button | the Button class}
+ *
+ * Suppose the `Button` class is part of an external package.  In that case, we
+ * can include the package name when referring to it:
+ *
+ * {@link my-control-library#Button | the Button class}
+ *
+ * The package name can include an NPM scope and import path:
+ *
+ * {@link @microsoft/my-control-library/lib/Button#Button | the Button class}
+ *
+ * The TSDoc standard calls this notation a "declaration reference".  The notation supports
+ * references to many different kinds of TypeScript declarations.  This notation was originally
+ * designed for use in `{@link}` and `{@inheritDoc}` tags, but you can also use it in your
+ * own custom tags.
+ *
+ * For example, the `Button` can be part of a TypeScript namespace:
+ *
+ * {@link my-control-library#controls.Button | the Button class}
+ *
+ * We can refer to a member of the class:
+ *
+ * {@link controls.Button.render | the render() method}
+ *
+ * If a static and instance member have the same name, we can use a selector to distinguish them:
+ *
+ * {@link controls.Button.(render:instance) | the render() method}
+ *
+ * {@link controls.Button.(render:static) | the render() static member}
+ *
+ * This is also how we refer to the class's constructor:
+ *
+ * {@link controls.(Button:constructor) | the class constructor}
+ *
+ * Sometimes a name has special characters that are not a legal TypeScript identifier:
+ *
+ * {@link restProtocol.IServerResponse."first-name" | the first name property}
+ *
+ * Here is a fairly elaborate example where the function name is an ECMAScript 6 symbol,
+ * and it's an overloaded function that uses a label selector (defined using the `{@label}`
+ * TSDoc tag):
+ *
+ * {@link my-control-library#Button.([UISymbols.toNumberPrimitive]:OVERLOAD_1)
+ * | the toNumberPrimitive() static member}
+ *
+ * See the TSDoc spec for more details about the "declaration reference" notation.
+ */
+```

pages/tags/override.md

@@ -18,7 +18,31 @@ A documentation tool may enforce that the `@virtual`, `@override`, and/or `@seal
 applied, but this is not required by the TSDoc standard.
 
 
+## Example
+
+In the code sample below, `Child.render()` overrides the virtual member `Base.render()`:
+
+```ts
+class Base {
+  /** @virtual */
+  public render(): void {
+  }
+
+  /** @sealed */
+  public initialize(): void {
+  }
+}
+
+class Child extends Base {
+  /** @override */
+  public render(): void;
+}
+```
+
+
 ## See also
 
 - [@sealed]({% link pages/tags/sealed.md %}) tag
 - [@virtual]({% link pages/tags/virtual.md %}) tag
+- [C# reference: override](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/override):
+  an equivalent feature from another programming language

pages/tags/packagedocumentation.md

@@ -14,3 +14,41 @@ Used to indicate a doc comment that describes an entire NPM package (as opposed
 to that package).  The `@packageDocumentation` comment is found in the *.d.ts file that acts as the entry point for
 the package, and it should be the first `/**` comment encountered in that file.  A comment containing
 a `@packageDocumentation` tag should never be used to describe an individual API item.
+
+
+## Example
+
+```ts
+// Copyright (c) Example Company. All rights reserved. Licensed under the MIT license.
+
+/**
+ * A library for building widgets.
+ *
+ * @remarks
+ * The `widget-lib` defines the {@link IWidget} interface and {@link Widget} class,
+ * which are used to build widgets.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Interface implemented by all widgets.
+ * @public
+ */
+export interface IWidget {
+  /**
+   * Draws the widget on the screen.
+   */
+  render(): void;
+}
+```
+
+
+## See also
+
+- [@alpha]({% link pages/tags/alpha.md %}) tag
+- [@beta]({% link pages/tags/beta.md %}) tag
+- [@experimental]({% link pages/tags/experimental.md %}) tag
+- [@public]({% link pages/tags/public.md %}) tag
+- [API Extractor: @packageDocumentation](https://api-extractor.com/pages/tsdoc/tag_packagedocumentation/):
+  a reference implementation of this feature

pages/tags/param.md

@@ -14,6 +14,29 @@ Used to document a function parameter.  The `@param` tag is followed by a parame
 followed by a description.
 
 
+## Example
+
+```ts
+/**
+ * Returns the average of two numbers.
+ *
+ * @remarks
+ * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
+ *
+ * @param x - The first input number
+ * @param y - The second input number
+ * @returns The arithmetic mean of `x` and `y`
+ *
+ * @beta
+ */
+function getAverage(x: number, y: number): number {
+  return (x + y) / 2.0;
+}
+```
+
+
 ## See also
 
 - [@returns]({% link pages/tags/returns.md %}) tag
+- [RFC #19](https://github.com/microsoft/tsdoc/issues/19): Support for dot syntax on `@param`
+- [Issue #151](https://github.com/microsoft/tsdoc/issues/151): Documenting the default value for a parameter

pages/tags/privateremarks.md

@@ -13,3 +13,32 @@ navigation_source: docs_nav
 Starts a section of additional documentation content that is not intended for a public audience.
 A tool must omit this entire section from the API reference web site, generated *.d.ts file,
 and any other outputs incorporating the content.
+
+
+## Example
+
+```ts
+/**
+ * The summary section should be brief. On a documentation web site,
+ * it will be shown on a page that lists summaries for many different
+ * API items.  On a detail page for a single item, the summary will be
+ * shown followed by the remarks section (if any).
+ *
+ * @remarks
+ *
+ * The main documentation for an API item is separated into a brief
+ * "summary" section optionally followed by an `@remarks` block containing
+ * additional details.
+ *
+ * @privateRemarks
+ *
+ * The `@privateRemarks` tag starts a block of additional commentary that is not meant
+ * for an external audience.  A documentation tool must omit this content from an
+ * API reference web site.  It should also be omitted when generating a normalized
+ * *.d.ts file.
+ */
+```
+
+## See also
+
+- [@remarks]({% link pages/tags/remarks.md %}) tag

pages/tags/public.md

@@ -14,9 +14,36 @@ Designates that an API item's release stage is "public".  It has been officially
 and its signature is guaranteed to be stable (e.g. following Semantic Versioning rules).
 
 
+## Example
+
+```ts
+/**
+ * Represents a book in the catalog.
+ * @public
+ */
+export class Book {
+  /**
+   * The title of the book.
+   * @internal
+   */
+  public get _title(): string;
+
+  /**
+   * The author of the book.
+   */
+  public get author(): string;
+};
+```
+
+In this example, `Book.author` inherits its `@public` designation from the containing class,
+whereas `Book._title` is marked as "internal".
+
+
 ## See also
 
 - [@alpha]({% link pages/tags/alpha.md %}) tag
 - [@beta]({% link pages/tags/beta.md %}) tag
 - [@experimental]({% link pages/tags/experimental.md %}) tag
 - [@internal]({% link pages/tags/public.md %}) tag
+- [Trimming based on release tags](https://api-extractor.com/pages/setup/configure_rollup/#trimming-based-on-release-tags):
+  a reference implementation of this feature

pages/tags/readonly.md

@@ -14,3 +14,23 @@ This modifier tag indicates that an API item should be documented as being read-
 type system may indicate otherwise.  For example, suppose a class property has a setter function that always
 throws an exception explaining that the property cannot be assigned; in this situation, the `@readonly` modifier
 can be added so that the property is shown as read-only in the documentation.
+
+
+## Example
+
+```ts
+export class Book {
+  /**
+   * Technically property has a setter, but for documentation purposes it should
+   * be presented as readonly.
+   * @readonly
+   */
+  public get title(): string {
+    return this._title;
+  }
+
+  public set title(value: string) {
+    throw new Error('This property is read-only!');
+  }
+}
+```

pages/tags/remarks.md

@@ -16,3 +16,32 @@ index pages (e.g. showing members of a class) will show only the brief summaries
 whereas a detail pages (e.g. describing a single member) will show the summary followed
 by the remarks.  The `@remarks` block tag ends the summary section, and begins the
 remarks section for a doc comment.
+
+
+## Example
+
+```ts
+/**
+ * The summary section should be brief. On a documentation web site,
+ * it will be shown on a page that lists summaries for many different
+ * API items.  On a detail page for a single item, the summary will be
+ * shown followed by the remarks section (if any).
+ *
+ * @remarks
+ *
+ * The main documentation for an API item is separated into a brief
+ * "summary" section optionally followed by an `@remarks` block containing
+ * additional details.
+ *
+ * @privateRemarks
+ *
+ * The `@privateRemarks` tag starts a block of additional commentary that is not meant
+ * for an external audience.  A documentation tool must omit this content from an
+ * API reference web site.  It should also be omitted when generating a normalized
+ * *.d.ts file.
+ */
+```
+
+## See also
+
+- [@privateRemarks]({% link pages/tags/privateremarks.md %}) tag

pages/tags/returns.md

@@ -13,6 +13,27 @@ navigation_source: docs_nav
 Used to document the return value for a function.
 
 
+## Example
+
+```ts
+/**
+ * Returns the average of two numbers.
+ *
+ * @remarks
+ * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
+ *
+ * @param x - The first input number
+ * @param y - The second input number
+ * @returns The arithmetic mean of `x` and `y`
+ *
+ * @beta
+ */
+function getAverage(x: number, y: number): number {
+  return (x + y) / 2.0;
+}
+```
+
+
 ## See also
 
 - [@param]({% link pages/tags/param.md %}) tag

pages/tags/sealed.md

@@ -18,7 +18,32 @@ A documentation tool may enforce that the `@virtual`, `@override`, and/or `@seal
 applied, but this is not required by the TSDoc standard.
 
 
+## Example
+
+In the code sample below, `Child.render()` overrides the virtual member `Base.render()`,
+but `Base.initialize()` must not be overridden because it is marked as "sealed".
+
+```ts
+class Base {
+  /** @virtual */
+  public render(): void {
+  }
+
+  /** @sealed */
+  public initialize(): void {
+  }
+}
+
+class Child extends Base {
+  /** @override */
+  public render(): void;
+}
+```
+
+
 ## See also
 
 - [@override]({% link pages/tags/override.md %}) tag
 - [@virtual]({% link pages/tags/virtual.md %}) tag
+- [C# reference: sealed](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/sealed):
+  an equivalent feature from another programming language

pages/tags/see.md

@@ -13,7 +13,11 @@ navigation_source: docs_nav
 Used to build a list of references to an API item or other resource that may be related to the
 current item.
 
-For example:
+> Note: JSDoc attempts to automatically hyperlink the text immediately after `@see`.  Because this is ambiguous
+> with plain text, TSDoc instead requires an explicit `{@link}` tag to make hyperlinks.
+
+
+## Example
 
 ```ts
 /**
@@ -42,5 +46,8 @@ Parses a string containing a Uniform Resource Locator (URL).
 - your developer SDK for code samples
 ```
 
-NOTE: JSDoc attempts to automatically hyperlink the text immediately after `@see`.  Because this is ambiguous
-with plain text, TSDoc instead requires an explicit `{@link}` tag to make hyperlinks.
+
+## See also
+
+- [RFC #235](https://github.com/microsoft/tsdoc/issues/235):
+  `@see` block tag specifies an item for a "See Also" section

pages/tags/throws.md

@@ -35,3 +35,8 @@ For example:
  */
 function fetchBookByIsbn(isbnCode: string): Book;
 ```
+
+
+## See also
+
+- [RFC 171](https://github.com/microsoft/tsdoc/issues/171): `@throws` tag for documenting exceptions

pages/tags/typeparam.md

@@ -13,3 +13,31 @@ navigation_source: docs_nav
 Used to document a generic parameter.  The `@typeParam` tag is followed by a parameter
 name, followed by a hyphen, followed by a description.  The TSDoc parser recognizes
 this syntax and will extract it into a DocParamBlock node.
+
+
+## Example
+
+```ts
+/**
+ * Alias for array
+ *
+ * @typeParam T - Type of objects the list contains
+ */
+type List<T> = Array<T>;
+
+/**
+ * Wrapper for an HTTP Response
+ * @typeParam B - Response body
+ * @param <H> - Headers
+ */
+interface HttpResponse<B, H> {
+    body: B;
+    headers: H;
+    statusCode: number;
+}
+```
+
+## See also
+
+- [RFC #72](https://github.com/microsoft/tsdoc/issues/72):
+  Support for `@typeparam` or `@template` for documenting generic parameters

pages/tags/virtual.md

@@ -17,7 +17,31 @@ A documentation tool may enforce that the `@virtual`, `@override`, and/or `@seal
 applied, but this is not required by the TSDoc standard.
 
 
+## Example
+
+In the code sample below, `Child.render()` overrides the virtual member `Base.render()`:
+
+```ts
+class Base {
+  /** @virtual */
+  public render(): void {
+  }
+
+  /** @sealed */
+  public initialize(): void {
+  }
+}
+
+class Child extends Base {
+  /** @override */
+  public render(): void;
+}
+```
+
+
 ## See also
 
 - [@override]({% link pages/tags/override.md %}) tag
 - [@sealed]({% link pages/tags/sealed.md %}) tag
+- [C# reference: virtual](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/virtual):
+  an equivalent feature from another programming language