Merge pull request #232 from arnog/patch-3

Clarify the behavior of @inheritdoc

Author: octogonz

common/changes/@microsoft/tsdoc/patch-3_2020-04-30-01-14.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Improve documentation for `@inheritDoc`",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "arnog@users.noreply.github.com"
+}

tsdoc/src/details/StandardTags.ts

@@ -124,6 +124,18 @@ export class StandardTags {
    * to the other item, which may be an unrelated class, or even an import from a
    * separate NPM package.
    *
+   * What gets copied
+   * 
+   * The `@inheritDoc` tag does not copy the entire comment body. Only the following 
+   * components are copied:
+   * - summary section
+   * - `@remarks` block
+   * - `@params` blocks
+   * - `@typeParam` blocks
+   * - `@returns` block
+   * Other tags such as `@defaultValue` or `@example` are not copied, and need to be 
+   * explicitly included after the `@inheritDoc` tag.
+   *
    * TODO: The notation for API item references is still being standardized.  See this issue:
    * https://github.com/microsoft/tsdoc/issues/9
    */