TypeStronggh-1556 make example tweaks as requested

example/README.md

@@ -32,10 +32,10 @@ the package.**
 
 Here are some examples we wanted to highlight:
 
-### Playgrounds
+### Rendering
 
--   Markdown playground: [[`markdownPlayground`]]
--   Syntax highlighting playground: [[`syntaxHighlightingPlayground`]]
+-   Markdown showcase: [[`markdownShowcase`]]
+-   Syntax highlighting showcase: [[`syntaxHighlightingShowcase`]]
 
 ### Functions
 
@@ -59,7 +59,7 @@ Here are some examples we wanted to highlight:
 
 ### Enums
 
--   Basic enums: [[`IntegerEnum`]] and [[`StringEnum`]]
+-   A basic enum: [[`SimpleEnum`]]
 -   Using the `@enum` tag: [[`EnumLikeObject`]]
 
 ### Variables

example/src/classes/CancellablePromise.ts

@@ -33,6 +33,9 @@ function isPromiseWithCancel<T>(value: unknown): value is PromiseWithCancel<T> {
  * - Complex method signatures
  * - Static methods
  * - A method with 10 overload signatures. Wow!
+ *     - Only the implementation signature has a doc comment. TypeDoc
+ *       automatically copies the comment from the implementation signature to
+ *       each of the visible signatures if they don't have one.
  *
  * A promise with a `cancel` method.  If canceled, the `CancellablePromise` will
  * reject with a `Cancellation` object. Originally from
@@ -193,14 +196,6 @@ export class CancellablePromise<T> {
         return new CancellablePromise(Promise.reject(reason), noop);
     }
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -216,14 +211,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -238,14 +225,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8, T9]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5, T6, T7, T8>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -259,14 +238,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5, T6, T7>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -279,14 +250,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5, T6>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -298,14 +261,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4, T5>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -316,14 +271,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4, T5]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3, T4>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -333,14 +280,6 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3, T4]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2, T3>(
         values: readonly [
             T1 | PromiseLike<T1>,
@@ -349,26 +288,10 @@ export class CancellablePromise<T> {
         ]
     ): CancellablePromise<[T1, T2, T3]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T1, T2>(
         values: readonly [T1 | PromiseLike<T1>, T2 | PromiseLike<T2>]
     ): CancellablePromise<[T1, T2]>;
 
-    /**
-     * Analogous to `Promise.all`.
-     *
-     * @param values an array that may contain `CancellablePromise`s, promises,
-     * thenables, and resolved values
-     * @returns a [[`CancellablePromise`]], which, if canceled, will cancel each
-     * of the promises passed in to `CancellablePromise.all`.
-     */
     static all<T>(
         values: readonly (T | PromiseLike<T>)[]
     ): CancellablePromise<T[]>;

example/src/enums.ts

@@ -1,37 +1,22 @@
-/** An integer enum. */
-export enum IntegerEnum {
+/** Describes the status of a delivery order. */
+export enum SimpleEnum {
+    /** This order has just been placed and is yet to be processed. */
     Pending,
 
-    /** Indicates that a courier is en route delivering this order. */
-    InProgress,
-
-    Complete,
-}
-
-/** A string enum. */
-export enum StringEnum {
-    Pending = "pending",
-
-    /** Indicates that a courier is en route delivering this order. */
-    InProgress = "inProgress",
-
-    Complete = "complete",
-}
-
-/** A [const enum](https://www.typescriptlang.org/docs/handbook/enums.html#const-enums). */
-export const enum ConstEnum {
-    Pending,
-
-    /** Indicates that a courier is en route delivering this order. */
+    /** A courier is en route delivering this order. */
     InProgress,
 
-    Complete,
+    /** The order has been delivered. */
+    Complete = "COMPLETE",
 }
 
 /**
  * [A crazy enum from the TypeScript
  * handbook](https://www.typescriptlang.org/docs/handbook/enums.html#computed-and-constant-members).
  * This enum contains both constant and computed members.
+ *
+ * TypeDoc won't show the value of computed members since this information is
+ * only available at runtime.
  */
 export enum CrazyEnum {
     // constant members
@@ -44,8 +29,6 @@ export enum CrazyEnum {
 }
 
 /**
- * @enum
- *
  * Since TypeScript's `enum` can be inconvenient to work with, some packages define their own enum-like objects:
  *
  * ```
@@ -57,6 +40,8 @@ export enum CrazyEnum {
  * ```
  *
  * Use the `@enum` tag to make TypeDoc document this object as an enum.
+ *
+ * @enum
  */
 export const EnumLikeObject = {
     Pending: "pending",

example/src/functions.ts

@@ -1,11 +1,3 @@
-/**
- * @module
- * This module demonstrates TypeDoc's support for functions.
- *
- * Use the [`@module`](https://typedoc.org/guides/doccomments/#%40module) tag to
- * tell TypeDoc that a comment block describes the entire module.
- */
-
 /**
  * Calculates the square root of a number.
  *

example/src/index.ts

@@ -4,6 +4,6 @@ export * from "./types";
 export * from "./classes";
 export * from "./enums";
 export * from "./reexports";
-export * from "./playground";
+export * from "./showcase";
 export * from "./reactComponents";
 export * from "./internals";

example/src/playground.ts → example/src/showcase.ts

@@ -1,5 +1,5 @@
 /**
- * # Markdown Playground
+ * # Markdown Showcase
  *
  * All comments are parsed as **Markdown**. TypeDoc uses the
  * [Marked](https://github.com/markedjs/marked) markdown parser to _convert
@@ -23,7 +23,7 @@
  * const x: number | string = 12
  * ```
  *
- * See [[`syntaxHighlightingPlayground`]] for more code blocks.
+ * See [[`syntaxHighlightingShowcase`]] for more code blocks.
  *
  * ## A List
  *
@@ -52,15 +52,8 @@
  *
  * This requires the [media option](https://typedoc.org/guides/options/#media)
  * to be set.
- *
- * ## An External Text Document
- *
- * [[include:file.txt]]
- *
- * This requires the [includes
- * option](https://typedoc.org/guides/options/#includes) to be set.
  */
-export function markdownPlayground(): void {
+export function markdownShowcase(): void {
     // does nothing
 }
 
@@ -119,7 +112,8 @@ export function markdownPlayground(): void {
  *
  * [**View the full list of supported
  * languages.**](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages)
+ * You can also get this list by running `typedoc --help`.
  */
-export function syntaxHighlightingPlayground(): void {
+export function syntaxHighlightingShowcase(): void {
     // does nothing
 }

example/typedoc.json

@@ -1,5 +1,4 @@
 {
     "sort": "source-order",
-    "media": "media",
-    "includes": "includes"
+    "media": "media"
 }