RFC: @includeSnippet tag for embedding code samples from external files

Hello,

I am looking for something similar to the @example tag, except I would like it to encapsulate real code, not something written in a comment.

My goal is to avoid the issue of writing examples that are out of date or inaccurate, which can happen when using the @example tag, because it's not real, tested code.

For example, this could be the package documentation:

/**
 * How to add your own custom recipe to this cook book app.
 * 
 * First, create a class that implements the IRecipe interface
 * @codeReference recipeDemoClass
 *
 * Then, register an instance of your class in your plugin's setup method.
 * @codeReference recipeDemoRegistration
 *
 * @packageDocumentation
 */

// some/path/to/demo_recipe/demo_recipe.ts

/**
 * @codeReferenceStart recipeDemoClass
 */
export class DemoRecipe extends IRecipe {
 ...
}
/**
 * @codeReferenceEnd recipeDemoClass
*/

// some/path/to/demo_recipe/plugin.ts

export class DemoRecipePlugin extends Plugin {
  setup(core, plugins) {
 /**
 * @codeReferenceStart recipeDemoRegistration
 */
  plugins.recipes.registerNewRecipe(new DemoRecipe());
/**
 * @codeReferenceEnd recipeDemoRegistration
*/
 }
}

The benefit of the end block is that you can call out specific snippets inside a function, not just entire exported functions.

Thoughts?

Note I also filed a similar feature request over in the Rushstack repo, but first this kind of tag would have to be part of the official TSDoc: https://github.com/microsoft/rushstack/issues/1640

Start by reviewing the proposed @codeReference, @codeReferenceStart, and @codeReferenceEnd tags in the issue body, then compare the related Rushstack issue 1640. No implementation files or tests are named; done would require a decided official TSDoc design for embedding external code snippets.