### Setup and Build TSDoc Projects

Source: https://tsdoc.org/pages/contributing/building

Navigates into the TSDoc directory, installs all project dependencies using Rush, and then builds the projects. This prepares the local environment for development and testing.

```bash
cd ./tsdoc
rush install
rush build
```

--------------------------------

### TSDoc @example Tag with Multiple Examples

Source: https://tsdoc.org/pages/tags/example

Demonstrates how to use the @example tag to include multiple code examples within a TSDoc comment. Each example can have its own descriptive title provided on the same line as the @example tag. The first example shows adding two numbers, and the second shows adding a positive and negative number.

```typescript
/**
 * 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 {}
```

--------------------------------

### TSDoc @example Tag for File Parsing

Source: https://tsdoc.org/pages/tags/example

Illustrates using the @example tag to document a function that parses a JSON file. This example includes the content of the JSON file, the TypeScript usage of the parsing function, and the expected result, providing a comprehensive example for the user.

```typescript
/**
 * 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',
 * }
 * ```
 */

```

--------------------------------

### Install Rush CLI

Source: https://tsdoc.org/pages/contributing/building

Installs the Rush command-line interface globally using npm. This is the first step to manage the monorepo.

```bash
npm install -g @microsoft/rush
```

--------------------------------

### Install Monorepo Dependencies with Rush

Source: https://tsdoc.org/pages/contributing/pr_checklist

Installs all project dependencies within the monorepo using the Rush tool. Ensure Rush is installed before running this command.

```shell
$ rush install
```

--------------------------------

### TypeScript Package Documentation Tag Example

Source: https://tsdoc.org/pages/tags/packagedocumentation

Demonstrates the usage of the @packageDocumentation tag in TypeScript. This tag is placed at the beginning of a .d.ts file to document the entire package. It includes an example interface and its methods.

```TypeScript
// 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;  
}
```

--------------------------------

### Install ESLint Plugin Dependencies

Source: https://tsdoc.org/pages/packages/eslint-plugin-tsdoc

Installs necessary ESLint and TypeScript development dependencies for a project.

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {},
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "~2.6.1",
    "@typescript-eslint/parser": "~2.6.1",
    "eslint": "~6.6.0",
    "typescript": "~3.7.2"
  },
  "scripts": {
    "lint": "eslint -f unix \"src/**/*.{ts,tsx}\""
  }
}
```

--------------------------------

### TSDoc Example: Function Documentation with @returns, @example, @see

Source: https://tsdoc.org/index

This snippet shows a TypeScript function declaration 'isInlineTag' with comprehensive TSDoc comments. It includes a description of the return value, an example demonstrating its usage with nested code blocks, and a see tag linking to an external resource. This illustrates advanced TSDoc usage for clarifying function behavior and providing usage examples.

```typescript
/**
 * @returns true if the specified tag is surrounded with {
 * and }
 * characters.
 *
 * @example
 * Prints "true" for `{@link}` but "false" for `@internal`:
 * ```ts
 * console.log(isInlineTag('{@link}'));
 * console.log(isInlineTag('@internal'));
 * ```
 * @see {@link http://example.com/@internal | the @internal tag}
 */
declare function isInlineTag(tagName: string): boolean;
```

--------------------------------

### API Usage: Loading and Configuring TSDocParser

Source: https://tsdoc.org/pages/packages/tsdoc-config

Provides a JavaScript code example for loading a tsdoc.json configuration and using it to initialize the TSDocParser.

```APIDOC
## API Usage: Loading and Configuring TSDocParser

### Description
This example shows how to use the `@microsoft/tsdoc-config` API to load a `tsdoc.json` file and configure the `TSDocParser` with its settings.

### Method
N/A (Code Example)

### Endpoint
N/A (Code Example)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
import * as path from 'path';
import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc';
import { TSDocConfigFile } from '@microsoft/tsdoc-config';

// Sample source file to be parsed
const mySourceFile: string = 'my-project/src/example.ts';

// Load the nearest config file, for example `my-project/tsdoc.json`
const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile));

if (tsdocConfigFile.hasErrors) {
  // Report any errors
  console.log(tsdocConfigFile.getErrorSummary());
}

// Use the TSDocConfigFile to configure the parser
const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
tsdocConfigFile.configureParser(tsdocConfiguration);
const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);
```

### Response
N/A (Code Example)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Add eslint-plugin-tsdoc

Source: https://tsdoc.org/pages/packages/eslint-plugin-tsdoc

Installs the eslint-plugin-tsdoc as a development dependency using npm.

```bash
$ cd my-project
$ npm install --save-dev eslint-plugin-tsdoc
```

--------------------------------

### TSDoc @remarks Tag Example

Source: https://tsdoc.org/pages/tags/remarks

This example demonstrates the correct usage of the @remarks tag within a TSDoc comment. It shows how to structure documentation with a summary, remarks, and privateRemarks.

```typescript
/**  
 * 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.  
 */  

```

--------------------------------

### Example Usage of @see Tag in TSDoc

Source: https://tsdoc.org/pages/tags/see

Demonstrates how to use the @see tag to reference related API items and external resources within TSDoc comments. It includes examples of linking to a defined type (ParsedUrl) and an external URL (RFC 1738).

```typescript
/**
 * Parses a string containing a Uniform Resource Locator (URL).
 * @see {@link ParsedUrl} for the returned data structure
 * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}
 * for syntax
 * @see your developer SDK for code samples
 * @param url - the string to be parsed
 * @returns the parsed result
 */
function parseURL(url: string): ParsedUrl;
```

--------------------------------

### TSDoc Block Tags Example

Source: https://tsdoc.org/pages/spec/tag_kinds

Demonstrates the usage of TSDoc block tags like @remarks and @example. Block tags can contain Markdown and other inline tags. The content before the first block tag is treated as the summary.

```typescript
/**  
 * This is the special summary section.  
 *  
 * @remarks  
 * This is a standalone block.  
 *  
 * @example Logging a warning  
 * ```ts  
 * logger.warn('Something happened');  
 * ```  
 *  
 * @example Logging an error  
 * ```ts  
 * logger.error('Something happened');  
 * ```  
 */  

```

--------------------------------

### Extend TSDoc configurations in tsdoc.json

Source: https://tsdoc.org/pages/packages/tsdoc-config

This JSON configuration demonstrates how to extend existing TSDoc configurations by specifying paths to other configuration files. Local paths must start with './' for correct resolution.

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-package/dist/tsdoc-base.json",
    "./path/to/local/file/tsdoc-local.json"
  ]
}
```

--------------------------------

### TypeScript @internal Tag Example

Source: https://tsdoc.org/pages/tags/internal

Demonstrates the usage of the @internal tag in TypeScript to denote an API item not intended for public consumption. The example shows a class with both public and internal members.

```typescript
/**  
 * 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;  
}
```

--------------------------------

### Run TSDoc Unit Tests (Watch Mode)

Source: https://tsdoc.org/pages/contributing/building

Starts the unit tests in watch mode using npm, allowing for interactive testing. Jest will automatically re-run affected tests when source files are saved.

```bash
cd ./tsdoc
npm run watch
```

--------------------------------

### TypeScript: @virtual and @override Usage Example

Source: https://tsdoc.org/pages/tags/virtual

Demonstrates how to use the @virtual modifier on a base class member and the @override modifier on a derived class member in TypeScript. This example illustrates subclassing and method overriding.

```typescript
class Base {
  /** @virtual */
  public render(): void {}

  /** @sealed */
  public initialize(): void {}
}

class Child extends Base {
  /** @override */
  public render(): void;
}
```

--------------------------------

### Demonstrates `{@link}` tag usage for URLs and API item references

Source: https://tsdoc.org/pages/tags/link

This example showcases the versatility of the `{@link}` tag. It illustrates how to link to external websites, specific API elements like classes and methods, and how to customize the displayed link text. It also covers advanced scenarios such as referencing items within external packages, namespaces, constructors, static members, overloaded functions, and properties with special characters.

```typescript
/**
 * 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.
 */
```

--------------------------------

### TSDoc @beta Tag Usage Example

Source: https://tsdoc.org/pages/tags/beta

Demonstrates how to apply the TSDoc @beta tag to a class member to indicate its beta release status. This example shows a 'Book' class where the 'title' property is marked as beta, while the 'author' property inherits the public designation from the class.

```typescript
/**
 * 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;
}
```

--------------------------------

### TSDoc Example: Class with Method Documentation

Source: https://tsdoc.org/index

This snippet demonstrates a TypeScript class 'Statistics' with a static method 'getAverage'. The method is documented using TSDoc comments, including remarks, parameters, return values, and a beta tag. This showcases how to structure documentation for methods in TypeScript.

```typescript
export class Statistics {
  /**
   * 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
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}
```

--------------------------------

### TSDoc @returns Example

Source: https://tsdoc.org/pages/tags/returns

Demonstrates the usage of the @returns tag within a TSDoc comment to describe the return value of the getAverage function. This includes parameter descriptions and remarks.

```typescript
/**
 * 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;
}
```

--------------------------------

### Deprecate a Class with TSDoc

Source: https://tsdoc.org/pages/tags/deprecated

This example shows how to use the @deprecated tag in TSDoc to mark a class as no longer supported. It includes a description of the recommended alternative, 'Control'.

```typescript
/**
 * The base class for controls that can be rendered.
 *
 * @deprecated Use the new {@link Control} base class instead.
 */
export class VisualControl {
  . . .
}
```

--------------------------------

### TypeScript Example of @override Modifier

Source: https://tsdoc.org/pages/tags/override

This example demonstrates the usage of the @override modifier in TypeScript. It shows a base class with virtual and sealed members, and a child class that overrides the virtual member using the @override tag. The @virtual and @sealed tags are also shown for context.

```typescript
class Base {
  /** @virtual */
  public render(): void {}

  /** @sealed */
  public initialize(): void {}
}

class Child extends Base {
  /** @override */
  public render(): void;
}
```

--------------------------------

### TypeScript Class with @experimental Tag

Source: https://tsdoc.org/pages/tags/experimental

This TypeScript example demonstrates the usage of the @experimental JSDoc tag on a class property. It indicates that the 'title' property is considered experimental, while inheriting the 'public' access modifier from its containing class.

```typescript
/**  
 * 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;  
}
```

--------------------------------

### Using @privateRemarks in Documentation Comments

Source: https://tsdoc.org/pages/tags/privateremarks

This example demonstrates the correct usage of the @privateRemarks tag within a JSDoc-style comment block. It shows how to include internal notes that should be excluded from public API documentation.

```typescript
/**
 * 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.
 */
```

--------------------------------

### TSDoc Inline Tags Example

Source: https://tsdoc.org/pages/spec/tag_kinds

Shows how TSDoc inline tags like {@link} and {@inheritDoc} are used within API documentation. Inline tags are embedded within Markdown content, enclosed in curly braces, to provide cross-references or inherit documentation.

```typescript
class Book {  
  /**  
   * Writes the book information into a JSON file.  
   *  
   * @remarks  
   * This method saves the book information to a JSON file conforming to the standardized  
   * {@link http://example.com/ | Example Book Interchange Format}.  
   */  
  public writeFile(options?: IWriteFileOptions): void {  
    . . .  
  }  
  
  /**  
   * {@inheritDoc Book.writeFile}  
   * @deprecated Use {@link Book.writeFile} instead.  
   */  
  public save(): void {  
    . . .  
  }  
}  

```

--------------------------------

### Documenting a Read-Only Property with @readonly

Source: https://tsdoc.org/pages/tags/readonly

This TypeScript example demonstrates how to use the @readonly TSDoc tag on a class property. It clarifies that the 'title' property, despite having a setter, should be presented as read-only in the generated documentation.

```typescript
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!');
  }
}
```

--------------------------------

### TypeScript API Item with @alpha Tag

Source: https://tsdoc.org/pages/tags/alpha

Demonstrates how to apply the '@alpha' JSDoc tag to a TypeScript class property to signify its alpha release status. This example shows inheritance of '@public' from the class while a specific property is marked as alpha.

```typescript
/**
 * 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;
}
```

--------------------------------

### TSDoc Modifier Tags Example

Source: https://tsdoc.org/pages/spec/tag_kinds

Illustrates TSDoc modifier tags such as @public and @sealed. Modifier tags denote special API properties and usually have no content. They are typically placed on a single line at the end of a doc comment.

```typescript
/**  
 * This is the special summary section.  
 *  
 * @remarks  
 * This is a standalone block.  
 *  
 * @public @sealed  
 */  

```

--------------------------------

### Marking an event property with @eventProperty

Source: https://tsdoc.org/pages/tags/eventproperty

This example demonstrates how to use the @eventProperty TSDoc tag on a class property. It indicates that the 'navigatedEvent' property returns an event object, suitable for attaching event handlers. The property's type is a generic 'FrameworkEvent' which typically includes methods like 'addHandler()' and 'removeHandler()'.

```typescript
class MyClass {
  /**
   * This event is fired whenever the application navigates to a new page.
   * @eventProperty
   */
  public readonly navigatedEvent: FrameworkEvent<NavigatedEventArgs>;
}
```

--------------------------------

### TSDoc Parser for @internal Tag Check

Source: https://tsdoc.org/pages/packages/tsdoc

An example of using the @microsoft/tsdoc parser to accurately determine if a TSDoc comment contains the '@internal' modifier tag. It demonstrates initializing the parser, processing a comment string, handling syntax errors, and accessing the modifier tag set.

```typescript
import { TSDocParser, ParserContext } from '@microsoft/tsdoc';

function isApiInternal(docComment: string): boolean {
  const tsdocParser: TSDocParser = new TSDocParser();

  // Analyze the input doc comment
  const parserContext: ParserContext = tsdocParser.parseString(docComment);

  // Check for any syntax errors
  if (parserContext.log.messages.length > 0) {
    throw new Error('Syntax error: ' + parserContext.log.messages[0].text);
  }

  // Since "@internal" is a standardized tag and a "modifier", it is automatically
  // added to the modifierTagSet:
  return parserContext.docComment.modifierTagSet.isInternal();
}

const input: string = [
  '/**',
  ' * @ Returns `true` if a comment string contains the',
  ' * {@link http://tsdoc.org/pages/tags/internal | @internal tag}.',
  ' *',
  ' * @example',
  ' * ```ts
  ' * // Prints "true" if comment contains "@internal"
  ' * console.log(isApiInternal(input));
  ' * ```',
  ' */'
].join('\n');

// Prints "false" because the two "@internal" usages in our example are embedded
// in other constructs, and thus should not be interpreted as tags.
console.log(isApiInternal(input));
```

--------------------------------

### TSDoc @sealed Modifier Example

Source: https://tsdoc.org/pages/tags/sealed

Demonstrates the usage of the @sealed modifier on a class member in TSDoc. The 'initialize' method in the 'Base' class is marked as sealed, preventing it from being overridden by the 'Child' class, while 'render' is virtual and correctly overridden.

```typescript
class Base {
  /** @virtual */
  public render(): void {}

  /** @sealed */
  public initialize(): void {}
}

class Child extends Base {
  /** @override */
  public render(): void;
}
```

--------------------------------

### Labeling Interface Members with @label

Source: https://tsdoc.org/pages/tags/label

This TypeScript code example demonstrates how to use the `{@label}` inline tag within TSDoc comments to label different members of an interface, including string indexers, number indexers, a functor (function signature), and a constructor. These labels are intended for use in TSDoc declaration references.

```typescript
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);
}
```

--------------------------------

### Build and Test All Projects with Rush

Source: https://tsdoc.org/pages/contributing/pr_checklist

Builds and tests all projects in the monorepo. This command ensures the integrity of the entire project after changes.

```shell
$ rush build
```

--------------------------------

### Run TSDoc Unit Tests (Build)

Source: https://tsdoc.org/pages/contributing/building

Executes the unit tests for the TSDoc projects by invoking the build script via npm. Tests are automatically run as part of the build process managed by Heft.

```bash
cd ./tsdoc
npm run build
```

--------------------------------

### @packageDocumentation Tag Usage

Source: https://tsdoc.org/pages/tags/packagedocumentation

The @packageDocumentation tag is used in the entry point .d.ts file of an NPM package to provide documentation for the entire package. It should be the first JSDoc comment in the file and should not be used to describe individual API items.

```APIDOC
## @packageDocumentation Tag

### Description
Used to indicate a doc comment that describes an entire NPM package. This tag should be placed in the *.d.ts file that acts as the entry point for the package, and it must be the first `/**` comment encountered in that file. A comment containing a `@packageDocumentation` tag should never be used to describe an individual API item.

### Parameters

#### No Parameters for Tag

This tag does not take any parameters directly. Its presence signifies the documentation scope.

### Example

```typescript
/**
 * 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 tag
* @beta tag
* @experimental tag
* @public tag
* API Extractor: @packageDocumentation: a reference implementation of this feature
```

--------------------------------

### Load and apply TSDoc configuration in TypeScript

Source: https://tsdoc.org/pages/packages/tsdoc-config

This TypeScript code demonstrates how to load a tsdoc.json configuration file and use it to configure the TSDocParser. It includes error handling for the configuration loading process.

```typescript
import * as path from 'path';
import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc';
import { TSDocConfigFile } from '@microsoft/tsdoc-config';

// Sample source file to be parsed
const mySourceFile: string = 'my-project/src/example.ts';

// Load the nearest config file, for example `my-project/tsdoc.json`
const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile));
if (tsdocConfigFile.hasErrors) {
  // Report any errors
  console.log(tsdocConfigFile.getErrorSummary());
}

// Use the TSDocConfigFile to configure the parser
const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
tsdocConfigFile.configureParser(tsdocConfiguration);
const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);
```

--------------------------------

### Using TSDoc parser from @microsoft/tsdoc package

Source: https://tsdoc.org/pages/intro/using_tsdoc

The @microsoft/tsdoc package provides a professional-quality parser for TSDoc comments. The 'api-demo' folder contains sample code demonstrating how to invoke this parser. This is useful for developers implementing tools that need to process doc comments.

```TypeScript
import * as tsdoc from "@microsoft/tsdoc";

// Example usage:
const parser = new tsdoc.TSDocParser();
const result = parser.parseString(
  "/**\n * This is a documentation comment.\n */\n",
  "MyFile.ts"
);

console.log(result.excerpt.text);

```

--------------------------------

### Create a Change Log Entry with Rush

Source: https://tsdoc.org/pages/contributing/pr_checklist

Generates a change entry for the CHANGELOG.md file, required when modifying published NPM packages. The tool prompts for a descriptive sentence.

```shell
$ rush change
# (The tool will ask you to write a sentence describing your change.)
```

--------------------------------

### TSDoc Configuration File with Extends

Source: https://tsdoc.org/pages/packages/tsdoc-config

Shows how to use the `extends` field to merge configurations from multiple files.

```APIDOC
## TSDoc Configuration File with Extends

### Description
Demonstrates using the `extends` field in `tsdoc.json` to incorporate configurations from other files, enabling shared or layered tag definitions.

### Method
N/A (Configuration File)

### Endpoint
N/A (Configuration File)

### Parameters
#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-package/dist/tsdoc-base.json",
    "./path/to/local/file/tsdoc-local.json"
  ]
}
```

### Response
N/A (Configuration File)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### TSDoc Configuration File Schema

Source: https://tsdoc.org/pages/packages/tsdoc-config

Illustrates the structure of a tsdoc.json file for defining custom TSDoc tags.

```APIDOC
## TSDoc Configuration File Schema

### Description
Defines the schema for `tsdoc.json` which is used to configure custom TSDoc tags.

### Method
N/A (Configuration File)

### Endpoint
N/A (Configuration File)

### Parameters
#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myTag",
      "syntaxKind": "modifier"
    }
  ]
}
```

### Response
N/A (Configuration File)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Debug TSDoc Unit Tests in VS Code

Source: https://tsdoc.org/pages/contributing/building

Opens the TSDoc subfolder in Visual Studio Code and configures it to debug Jest tests. This involves selecting the 'Debug Jest tests' configuration from the Run and Debug view.

```bash
cd ./tsdoc
code .
```

--------------------------------

### Documenting Exceptions with @throws

Source: https://tsdoc.org/pages/tags/throws

Demonstrates the usage of the @throws tag to document specific exception types that a function might throw. It shows how to link to exception types using {@link} and provide a description for each.

```typescript
/**
 * Retrieves metadata about a book from the catalog.
 *
 * @param isbnCode - the ISBN number for the book
 * @returns the retrieved book object
 *
 * @throws {@link IsbnSyntaxError}
 * This exception is thrown if the input is not a valid ISBN number.
 *
 * @throws {@link book-lib#BookNotFoundError}
 * Thrown if the ISBN number is valid, but no such book exists in the catalog.
 *
 * @public
 */
function fetchBookByIsbn(isbnCode: string): Book;
```

--------------------------------

### Build TSDoc Library with NPM

Source: https://tsdoc.org/pages/contributing/pr_checklist

Builds specifically the @microsoft/tsdoc library. This is useful for testing changes isolated to this package.

```shell
cd ./tsdoc
npm run build
```

--------------------------------

### Configure ESLint for TSDoc Syntax

Source: https://tsdoc.org/pages/packages/eslint-plugin-tsdoc

Configures ESLint to use the tslint-plugin-tsdoc, enabling the 'tsdoc/syntax' rule for TSDoc validation. This includes setting up TypeScript parsing and extending recommended ESLint configurations.

```javascript
module.exports = {
  plugins: ['@typescript-eslint/eslint-plugin', 'eslint-plugin-tsdoc'],
  extends: ['plugin:@typescript-eslint/recommended'],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: './tsconfig.json',
    tsconfigRootDir: __dirname,
    ecmaVersion: 2018,
    sourceType: 'module'
  },
  rules: {
    'tsdoc/syntax': 'warn'
  }
};
```

--------------------------------

### Documenting Function Parameters with @param in TypeScript

Source: https://tsdoc.org/pages/tags/param

Demonstrates the standard usage of the @param tag within a JSDoc comment block to describe function parameters. It specifies the parameter name, a hyphen, and a detailed description, along with other relevant tags like @remarks and @returns.

```typescript
/**
 * 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;
}
```

--------------------------------

### TypeScript @inheritDoc for API Documentation

Source: https://tsdoc.org/pages/tags/inheritdoc

Demonstrates the usage of the @inheritDoc inline tag in TypeScript to copy documentation from an interface method to a class method, and from an external library's method.

```typescript
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 {
    . . .
  }
}
```

--------------------------------

### Document Generic HTTP Response Interface with @typeParam

Source: https://tsdoc.org/pages/tags/typeparam

Shows how to use the @typeParam tag to document multiple generic type parameters (B for Response body, H for Headers) in a TypeScript interface for an HTTP response.

```typescript
/**
 * Wrapper for an HTTP Response
 * @typeParam B - Response body
 * @param <H> - Headers
 */
interface HttpResponse<B, H> {
  body: B;
  headers: H;
  statusCode: number;
}
```

--------------------------------

### Documenting ECMAScript Decorators with @decorator

Source: https://tsdoc.org/pages/tags/decorator

This snippet demonstrates how to use the TSDoc @decorator tag to document ECMAScript decorators within a class property. It shows the relationship between the doc comment tag and the actual decorator applied to the property.

```typescript
class Book {
  /**
   * The title of the book.
   * @decorator `@jsonSerialized`
   * @decorator `@jsonFormat(JsonFormats.Url)`
   */
  @jsonSerialized
  @jsonFormat(JsonFormats.Url)
  public website: string;
}
```

--------------------------------

### TypeScript Class with @public and @internal Tags

Source: https://tsdoc.org/pages/tags/public

This TypeScript code demonstrates the usage of the @public and @internal JSDoc tags within a class definition. The @public tag designates the 'author' getter as part of the public API, while @internal marks the '_title' getter as internal.

```typescript
/**
 * 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;
}
```

--------------------------------

### Document Generic List Type with @typeParam

Source: https://tsdoc.org/pages/tags/typeparam

Demonstrates using the @typeParam tag to document the generic type parameter 'T' for a TypeScript type alias representing a list.

```typescript
/**
 * Alias for array
 *
 * @typeParam T - Type of objects the list contains
 */
type List<T> = Array<T>;
```

--------------------------------

### Documenting @defaultValue for TypeScript Interface Properties

Source: https://tsdoc.org/pages/tags/defaultvalue

This TypeScript code snippet demonstrates the usage of the @defaultValue TSDoc tag to document the default values for properties within an interface. It shows how to specify default values for an enum-based property and a boolean property, along with relevant remarks.

```typescript
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;
}
```

--------------------------------

### Define custom TSDoc tags in tsdoc.json

Source: https://tsdoc.org/pages/packages/tsdoc-config

This JSON configuration defines a custom TSDoc tag named "@myTag" with a "modifier" syntax kind. It uses the TSDoc schema to validate the structure.

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myTag",
      "syntaxKind": "modifier"
    }
  ]
}
```

--------------------------------

### Simple @internal Tag Check (RegExp)

Source: https://tsdoc.org/pages/packages/tsdoc

A basic JavaScript function using a regular expression to check if a comment string contains the '@internal' tag. It handles cases where '@internal' might be part of another word or sentence.

```javascript
function isApiInternal(docComment: string): boolean {
  return /(^|\s)@internal(\s|$)/.test(docComment);
}
```

--------------------------------

### TSDoc Standardization Enum

Source: https://tsdoc.org/pages/spec/standardization_groups

Represents the different levels of support for TSDoc tags. The enum values are Core, Extended, and Discretionary.

```typescript
export enum Standardization {
  Core = "Core",
  Extended = "Extended",
  Discretionary = "Discretionary"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.