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

[octogonz]

Right, TSDoc is designed for generating the “API Reference” section of your documentation. This is the section that shows all the classes/enums/etc in a big index. The API Reference is often authored by software engineers, or at least they write the initial draft of the content at the same time as they are designing the APIs. That’s why it makes sense to store it in code comments. Updating this documentation usually requires creating a pull request for the actual code base.

Typically, the documentation system will also have a lot of free-form content such as walkthroughs, best practices, etc. This part may be authored by technical writers who would find it inconvenient to have to make pull requests into the product code base (and maybe won’t even have permissions). Thus these pages are usually authored as standalone .md files, maybe in a completely different repository.

Here’s an example from Microsoft SharePoint which uses DocFX. These API Reference pages were generated from the code comments using API Extractor:

• sp-application-base package
• ApplicationAccessor class
• etc

…whereas these free-form pages were manually authored as DocFX .md files (and note how the table of contents seamlessly integrates these two sections):

• SharePoint development overview
• Tutorials
• etc

And here’s an example from Rush Stack which uses Jekyll documentation system. These API Reference pages were generated by API Extractor:

• API Reference
• IFeatureDefinition.kind property
• etc

…whereas these pages were manually authored as Jekyll .md files:

• Project roadmap
• Getting Started
• etc

Code snippets are useful in both the API Reference and the free-form sections. I think in both cases it would be desirable to compile the code to ensure there are no mistakes. Thus…

If you are writing long-form tutorials for big scenarios, it would make sense to model that as regular .md files. Your documentation system probably provides some way to extract excerpts from files. (For example, DocFX !code directives.)

If you are providing brief code samples illustrating a specific API, it would make sense to embed that in the API reference, in which case the proposed TSDoc @includeSnippet tag would be useful.

[octogonz]

Would this potentially enable inserting Markdown snippets from another file? I assume you could use this as a general text insertion mechanism but wasn’t sure if the content would be processed as Markdown after inserted.

If we require that the @includeSnippet path always includes the file extension, then this should work with any file. The syntax highlighting can be inferred, rather than explicitly specified as with a Markdown code fence (```ts).

Maybe part of the definition of a “snippet” is that it gets rendered as code. If we want to insert content from a .md file and have it rendered as Markdown, that seems like a separate scenario. Perhaps it should have its own tag (@include?) and be designed separately. The requirements are probably somewhat different.

I think my preference would be to disallow @snippetStart from not containing a label and have @includeSnippet with no label always include the whole file. The reason for this is that adding a second snippet in a file that used @snippetStart with no label could accidentally change the generated output without the author of the original document or possibly the person adding the new snippet realizing it.

👍 Makes sense.

@stacey-gammon What do you think?