RFC: A tag for customizing IntelliSense tooltips

[octogonz]

In #8 (comment) @bookmoons said:

Suggested in microsoft/vscode#77261 something like @extended and @extendedExample that's intended to land in docs but not be shown in smaller contexts like IntelliSense.

/**
 * Take over the specified world.
 * 
 * @param world - The world to dominate.
 * 
 * @remarks
 * Optimizes for minimum loss of life, minimum reputation harm, and maximum deviousness.
 * Leverages all available capital and human resources without remorse.
 *
 * @extended
 * The development of this procedure began with the Sumerian kings.
 * [... long history ...]
 * 
 * @extendedExample
 * // Example of error handling based on the latest best practices
 * while (!retired) {
 *   try { takeOverWorld(earth) } catch (error) {
 *     if (error instanceof InsurrectionError) squashInsurrection()
 *     else if (error instanceof CoupError) decimateCoup()
 *     else if (error instanceof GlobalThermonuclearWarError) retire()
 *     [.. long example list .. ]
 *   }
 * }
 *
 * @beta
 */
export function takeOverWorld(world: World): void;

I've opened this issue so we can have a more focused discussion.

[octogonz]

@bookmooons Are you sure that annotating core/extended text needs to be the burden of the documentation author?

Different IntelliSense engines may have different requirements:

• the tooltip box may be larger or smaller
• it may be scrollable or not
• they may or may not know how to render certain constructs

I agree that the VS Code IntelliSense could present the content more nicely. However, I wonder if that can be fixed without any additional accommodations from TSDoc. Maybe there's already enough information in the AST to implement a reasonable heuristic.