Add support for the @inheritDoc tag

tsdoc/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log - @microsoft/tsdoc
 
+## 0.6.0
+- Add support for `@link` tags using the new declaration reference syntax
+- Add support for `@inheritDoc` tags
+- Add new APIs: `DocDeclarationReference`, `DocInheritDocTag`, `DocLinkTag`, `DocMemberIdentifier`, `DocMemberReference`, `DocMemberSelector`, `DocMemberSymbol`
+- Remove `ParserContext.verbatimNodes`
+- Add `DocParticle.particleId` property
+
 ## 0.5.0
 - Add a new API `DocNode.updateParameters()` that allows a `DocNode` object to be updated after it was created; the tree nodes are no longer immutable
 - Add `DocNodeTransforms.trimSpacesInParagraphNodes()` for collapsing whitespace inside `DocParagraph` subtrees

tsdoc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/tsdoc",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A parser for the TypeScript doc comment syntax",
   "keywords": [
     "TypeScript",

tsdoc/src/nodes/DocBlock.ts

@@ -14,7 +14,7 @@ export interface IDocBlockParameters extends IDocSectionParameters {
  * For example, an `@example` block.
  */
 export class DocBlock extends DocSection {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.Block;
 
   private _blockTag: DocBlockTag | undefined; // never undefined after updateParameters()
@@ -41,7 +41,7 @@ export class DocBlock extends DocSection {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocBlockTag.ts

@@ -13,7 +13,7 @@ export interface IDocBlockTagParameters extends IDocNodeLeafParameters {
  * Represents a TSDoc block tag such as `@param` or `@public`.
  */
 export class DocBlockTag extends DocNodeLeaf {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.BlockTag;
 
   private _tagName: string | undefined;              // never undefined after updateParameters()

tsdoc/src/nodes/DocCodeFence.ts

@@ -23,7 +23,7 @@ export interface IDocCodeFenceParameters extends IDocNodeParameters {
  * can also specify a language for a syntax highlighter.
  */
 export class DocCodeFence extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.CodeFence;
 
   // The opening ``` delimiter and padding
@@ -102,7 +102,7 @@ export class DocCodeFence extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocCodeSpan.ts

@@ -19,7 +19,7 @@ export interface IDocCodeSpanParameters extends IDocNodeParameters {
  * backtick characters.
  */
 export class DocCodeSpan extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.CodeSpan;
 
   // The opening ` delimiter
@@ -70,7 +70,7 @@ export class DocCodeSpan extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocComment.ts

@@ -3,6 +3,7 @@ import { DocSection } from './DocSection';
 import { StandardModifierTagSet } from '../details/StandardModifierTagSet';
 import { DocBlock } from './DocBlock';
 import { DocParamBlock } from './DocParamBlock';
+import { DocInheritDocTag } from './DocInheritDocTag';
 
 /**
  * Constructor parameters for {@link DocComment}.
@@ -15,7 +16,7 @@ export interface IDocCommentParameters extends IDocNodeParameters {
  * This is the root of the DocNode tree.
  */
 export class DocComment extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.Comment;
 
   /**
@@ -72,6 +73,12 @@ export class DocComment extends DocNode {
    */
   public returnsBlock: DocBlock | undefined;
 
+  /**
+   * If this doc comment contains an `@inheritDoc` tag, it will be extracted and associated
+   * with the DocComment.
+   */
+  public inheritDocTag: DocInheritDocTag | undefined;
+
   /**
    * The modifier tags for this DocComment.
    */
@@ -113,36 +120,20 @@ export class DocComment extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {
-    const result: DocNode[] = [ ];
-
-    result.push(this.summarySection);
-
-    if (this.remarksBlock) {
-      result.push(this.remarksBlock);
-    }
-
-    if (this.privateRemarks) {
-      result.push(this.privateRemarks);
-    }
-
-    if (this.deprecatedBlock) {
-      result.push(this.deprecatedBlock);
-    }
-
-    result.push(...this.paramBlocks);
-
-    if (this.returnsBlock) {
-      result.push(this.returnsBlock);
-    }
-
-    result.push(...this._customBlocks);
-
-    result.push(...this.modifierTagSet.nodes);
-
-    return result;
+    return DocNode.trimUndefinedNodes([
+      this.summarySection,
+      this.remarksBlock,
+      this.privateRemarks,
+      this.deprecatedBlock,
+      ...this.paramBlocks,
+      this.returnsBlock,
+      ...this._customBlocks,
+      this.inheritDocTag,
+      ...this.modifierTagSet.nodes
+    ]);
   }
 }

tsdoc/src/nodes/DocDeclarationReference.ts

@@ -26,7 +26,7 @@ export interface IDocDeclarationReferenceParameters extends IDocNodeParameters {
  * or `{@inheritDoc}` that need to refer to another declaration.
  */
 export class DocDeclarationReference extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.DeclarationReference;
 
   private _packageNameParticle: DocParticle | undefined;
@@ -117,7 +117,7 @@ export class DocDeclarationReference extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocErrorText.ts

@@ -16,7 +16,7 @@ export interface IDocErrorTextParameters extends IDocNodeLeafParameters {
  * The characters should be rendered as plain text.
  */
 export class DocErrorText extends DocNodeLeaf {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.ErrorText;
 
   private _text: string | undefined;                  // never undefined after updateParameters()

tsdoc/src/nodes/DocEscapedText.ts

@@ -27,7 +27,7 @@ export enum EscapeStyle {
  * forces a specific escaping that may not be the default.
  */
 export class DocEscapedText extends DocNodeLeaf {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.EscapedText;
 
   private _escapeStyle: EscapeStyle | undefined;  // never undefined after updateParameters()

tsdoc/src/nodes/DocHtmlAttribute.ts

@@ -24,7 +24,7 @@ export interface IDocHtmlAttributeParameters extends IDocNodeParameters {
  * Example: `href="#"` inside `<a href="#" />`
  */
 export class DocHtmlAttribute extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.HtmlAttribute;
 
   // The attribute name
@@ -109,7 +109,7 @@ export class DocHtmlAttribute extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocHtmlEndTag.ts

@@ -18,7 +18,7 @@ export interface IDocHtmlEndTagParameters extends IDocNodeParameters {
  * Represents an HTML end tag.  Example: `</a>`
  */
 export class DocHtmlEndTag extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.HtmlEndTag;
 
   // The "</" delimiter
@@ -69,7 +69,7 @@ export class DocHtmlEndTag extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocHtmlStartTag.ts

@@ -25,7 +25,7 @@ export interface IDocHtmlStartTagParameters extends IDocNodeParameters {
  * Example: `<a href="#" />`
  */
 export class DocHtmlStartTag extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.HtmlStartTag;
 
   // The "<" delimiter
@@ -107,7 +107,7 @@ export class DocHtmlStartTag extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocInheritDocTag.ts

@@ -0,0 +1,65 @@
+import { DocNodeKind, DocNode } from './DocNode';
+import { DocInlineTag, IDocInlineTagParameters } from './DocInlineTag';
+import { DocDeclarationReference } from './DocDeclarationReference';
+
+/**
+ * Constructor parameters for {@link DocInheritDocTag}.
+ */
+export interface IDocInheritDocTagParameters extends IDocInlineTagParameters {
+  declarationReference?: DocDeclarationReference;
+}
+
+/**
+ * Represents an `{@inheritDoc}` tag.
+ */
+export class DocInheritDocTag extends DocInlineTag {
+
+  /** {@inheritDoc} */
+  public readonly kind: DocNodeKind = DocNodeKind.InheritDocTag;
+
+  private _declarationReference: DocDeclarationReference | undefined;
+
+  /**
+   * Don't call this directly.  Instead use {@link TSDocParser}
+   * @internal
+   */
+  public constructor(parameters: IDocInheritDocTagParameters) {
+    super(parameters);
+  }
+
+  /**
+   * The declaration that the documentation will be inherited from.
+   * If omitted, the documentation will be inherited from the parent class.
+   */
+  public get declarationReference(): DocDeclarationReference | undefined {
+    return this._declarationReference;
+  }
+
+  /** @override */
+  public updateParameters(parameters: IDocInheritDocTagParameters): void {
+    if (parameters.tagName.toUpperCase() !== '@INHERITDOC') {
+      throw new Error('DocInheritDocTag requires the tag name to be "{@inheritDoc}"');
+    }
+
+    super.updateParameters(parameters);
+
+    this._declarationReference = parameters.declarationReference;
+  }
+
+  /**
+   * {@inheritDoc}
+   * @override
+   */
+  protected getChildNodesForContent(): ReadonlyArray<DocNode> {
+    if (this.tagContentParticle.excerpt) {
+      // If the parser associated the inline tag input with the tagContentExcerpt (e.g. because
+      // second stage parsing encountered an error), then fall back to the base class's representation
+      return super.getChildNodesForContent();
+    } else {
+      // Otherwise return the detailed structure
+      return DocNode.trimUndefinedNodes([
+        this._declarationReference
+      ]);
+    }
+  }
+}

tsdoc/src/nodes/DocInlineTag.ts

@@ -19,10 +19,10 @@ export interface IDocInlineTagParameters extends IDocNodeParameters {
 }
 
 /**
- * Represents a TSDoc inline tag such as `{@inheritdoc}` or `{@link}`.
+ * Represents a TSDoc inline tag such as `{@inheritDoc}` or `{@link}`.
  */
 export class DocInlineTag extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.InlineTag;
 
   private _openingDelimiterParticle: DocParticle | undefined;  // never undefined after updateParameters()
@@ -88,7 +88,7 @@ export class DocInlineTag extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override @sealed
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocLinkTag.ts

@@ -24,7 +24,7 @@ export interface IDocLinkTagParameters extends IDocInlineTagParameters {
  */
 export class DocLinkTag extends DocInlineTag {
 
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.LinkTag;
 
   private _codeDestination: DocDeclarationReference | undefined;
@@ -130,7 +130,7 @@ export class DocLinkTag extends DocInlineTag {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   protected getChildNodesForContent(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocMemberIdentifier.ts

@@ -19,7 +19,7 @@ export interface IDocMemberIdentifierParameters extends IDocNodeParameters {
  * A member identifier is part of a {@link DocMemberReference}.
  */
 export class DocMemberIdentifier extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.MemberIdentifier;
 
   private _leftQuoteParticle: DocParticle | undefined;
@@ -97,7 +97,7 @@ export class DocMemberIdentifier extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {

tsdoc/src/nodes/DocMemberReference.ts

@@ -33,7 +33,7 @@ export interface IDocMemberReferenceParameters extends IDocNodeParameters {
  * `ui`, `.controls`, and `.Button`, and `.(render:static)`.
  */
 export class DocMemberReference extends DocNode {
-  /** {@inheritdoc} */
+  /** {@inheritDoc} */
   public readonly kind: DocNodeKind = DocNodeKind.MemberReference;
 
   // The "." token if unless this was the member reference in the chain
@@ -148,7 +148,7 @@ export class DocMemberReference extends DocNode {
   }
 
   /**
-   * {@inheritdoc}
+   * {@inheritDoc}
    * @override
    */
   public getChildNodes(): ReadonlyArray<DocNode> {