Adding examples (@example) to the documentation

[bali182]

Thanks for the really great documentation tool!

I was wondering, if there is any way to add examples directly into the doccoment? I noticed, that adding custom tags like @whatever shows up in the generated documentation, and if I use the triple quote markdown syntax, I get syntax highlighting. It also looks like, that @example is not treated as a special annotiation. But is the @example & markdown combo the standard way of adding API examples to your source? Is there a standard way at all?

[sebastian-lenz]

Hi Édes, nice to hear from you. TypeDoc currently has no explicit support for the @example tag, I've always preferred to include samples within the comment body itself using the markdown syntax for code blocks.

The "official" JSDoc implementation supports the @example tag, see here. TypeDoc is not aiming at being fully aligned to JSDoc but maybe we should give the @example special treatment too.

[bali182]

Thanks for the quick response, Sebastian! I think, it would be a very nice extension of the existing functionality, if @example would be available :) If you consider adding it, let me know if I can help in any way!

[MartinSvarrer]

Just found this issue as I tried the same combination, expecting @example and code snippets to work together. Instead I just get a tag on top of my snippet, pushing my code.

[stepancar]

+1 need too:)

[tomlarkworthy]

I have tried triple markdown but the whitespace seems to get stripped? Some help on inserting code blocks would be greatly appreciated

[landonpoch]

I tried markdown syntax and it appears to work just fine. In my mind this issue isn't that critical. However, it might be nice to see the example tag show up above the examples that are included in the docs.

[jtraband]

Fenced code blocks do seems to have whitespace stripped. ( per comment above). This does make it difficult to include multiline examples in the docs.

[amarzavery]

Update: I was able to preserve whitespaces/indentation. One needs to start the example with stars (*).

  /**
   * . . . 
   * @example
   * ```typescript
   * 
   *const resourceGroupName = 'res9101';
   *const accountName = 'sto4445';
   *const parameters: StorageManagementModels.StorageAccountCreateParameters = {
   *  sku: {
   *    name: <StorageManagementModels.SkuName>'Standard_GRS'
   *  },
   *  kind: <StorageManagementModels.Kind>'Storage',
   *  location: 'eastus2euap',
   *  tags: {
   *    "key1": "value1",
   *    "key2": "value2"
   *  }
   * };
   *const storageAccount = await client.storageAccounts.create(resourceGroupName, accountName, parameters);
   * ``` 
   * @param {string} resourceGroupName The name of the resource group within the
   * user's subscription. The name is case insensitive.
   * . . .
   */

As you can see the indentation is preserved in the example.

[Gerrit0]

With TypeDoc 0.23 (currently sitting on the beta branch, no release yet since I broke lots of things...), TypeDoc is much smarter about parsing comments, it will correctly handle indentation in code blocks, even without leading *s on each line.

Note: TypeDoc and JSDoc disagree about what an @example block contains. Both TypeDoc and TSDoc say that it contains regular text, like any other block, and may contain a code block. JSDoc says that the @example block is implicitly a code block.