MarkdownDocumenter now writes @deprecated warnings

Author: pgonzal

apps/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -19,7 +19,8 @@ import {
   DocCodeSpan,
   DocFencedCode,
   StandardTags,
-  DocBlock
+  DocBlock,
+  DocComment
 } from '@microsoft/tsdoc';
 import {
   ApiModel,
@@ -117,8 +118,27 @@ export class MarkdownDocumenter {
     }
 
     if (apiItem instanceof ApiDocumentedItem) {
-      if (apiItem.tsdocComment) {
-        this._appendSection(output, apiItem.tsdocComment.summarySection);
+      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
+
+      if (tsdocComment) {
+
+        if (tsdocComment.deprecatedBlock) {
+          output.appendNode(
+            new DocNoteBox({ configuration: this._tsdocConfiguration },
+              [
+                new DocParagraph({ configuration: this._tsdocConfiguration }, [
+                  new DocPlainText({
+                    configuration: this._tsdocConfiguration,
+                    text: 'Warning: This API is now obsolete. '
+                  })
+                ]),
+                ...tsdocComment.deprecatedBlock.content.nodes
+              ]
+            )
+          );
+        }
+
+        this._appendSection(output, tsdocComment.summarySection);
       }
     }
 
@@ -161,15 +181,17 @@ export class MarkdownDocumenter {
     }
 
     if (apiItem instanceof ApiDocumentedItem) {
-      if (apiItem.tsdocComment) {
+      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
+
+      if (tsdocComment) {
         // Write the @remarks block
-        if (apiItem.tsdocComment.remarksBlock) {
+        if (tsdocComment.remarksBlock) {
           output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Remarks' }));
-          this._appendSection(output, apiItem.tsdocComment.remarksBlock.content);
+          this._appendSection(output, tsdocComment.remarksBlock.content);
         }
 
         // Write the @example blocks
-        const exampleBlocks: DocBlock[] = apiItem.tsdocComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
+        const exampleBlocks: DocBlock[] = tsdocComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
           === StandardTags.example.tagNameWithUpperCase);
 
         let exampleNumber: number = 1;

apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts

@@ -68,10 +68,14 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
       case CustomDocNodeKind.NoteBox: {
         const docNoteBox: DocNoteBox = docNode as DocNoteBox;
         writer.ensureNewLine();
-        writer.write('> ');
-        // TODO: Handle newlines
+
+        writer.increaseIndent('> ');
+
         this.writeNode(docNoteBox.content, context);
         writer.ensureNewLine();
+
+        writer.decreaseIndent();
+
         writer.writeLine();
         break;
       }

apps/api-extractor/src/api/IndentedWriter.ts

@@ -157,6 +157,10 @@ export class IndentedWriter {
    * each line will be indented separately.
    */
   public write(message: string): void {
+    if (message.length === 0) {
+      return;
+    }
+
     // If there are no newline characters, then append the string verbatim
     if (!/[\r\n]/.test(message)) {
       this._writeLinePart(message);
@@ -182,7 +186,9 @@ export class IndentedWriter {
    * Indentation is applied following the semantics of IndentedWriter.write().
    */
   public writeLine(message: string = ''): void {
-    this.write(message);
+    if (message.length > 0) {
+      this.write(message);
+    }
     this._writeNewLine();
   }
 
@@ -200,6 +206,10 @@ export class IndentedWriter {
   }
 
   private _writeNewLine(): void {
+    if (this._atStartOfLine && this._indentText.length > 0) {
+      this._write(this._indentText);
+    }
+
     this._write('\n');
     this._atStartOfLine = true;
   }

apps/api-extractor/src/api/test/IndentedWriter.test.ts

@@ -26,6 +26,12 @@ test('02 Indent something', () => {
   indentedWriter.decreaseIndent();
   indentedWriter.writeLine('e');
 
+  indentedWriter.increaseIndent('>>> ');
+    indentedWriter.writeLine();
+    indentedWriter.writeLine();
+    indentedWriter.writeLine('g');
+  indentedWriter.decreaseIndent();
+
   expect(indentedWriter.toString()).toMatchSnapshot();
 });
 

apps/api-extractor/src/api/test/__snapshots__/IndentedWriter.test.ts.snap

@@ -11,6 +11,9 @@ exports[`02 Indent something 1`] = `
 "abc
   d
 e
+>>> 
+>>> 
+>>> g
 "
 `;
 

build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.docclass1.deprecatedexample.md

@@ -0,0 +1,18 @@
+[Home](./index) > [api-extractor-test-05](./api-extractor-test-05.md) > [DocClass1](./api-extractor-test-05.docclass1.md) > [deprecatedExample](./api-extractor-test-05.docclass1.deprecatedexample.md)
+
+## DocClass1.deprecatedExample() method
+
+> Warning: This API is now obsolete.
+> 
+> Use `otherThing()` instead.
+> 
+
+<b>Signature:</b>
+
+```typescript
+deprecatedExample(): void;
+```
+<b>Returns:</b>
+
+`void`
+

build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.docclass1.md

@@ -27,6 +27,7 @@ export declare class DocClass1
 
 |  <p>Method</p> | <p>Modifiers</p> | <p>Description</p> |
 |  --- | --- | --- |
+|  <p>[deprecatedExample()](./api-extractor-test-05.docclass1.deprecatedexample.md)</p> |  |  |
 |  <p>[exampleFunction(a, b)](./api-extractor-test-05.docclass1.examplefunction.md)</p> |  | <p>This is an overloaded function.</p> |
 |  <p>[exampleFunction(x)](./api-extractor-test-05.docclass1.examplefunction_1.md)</p> |  | <p>This is also an overloaded function.</p> |
 |  <p>[interestingEdgeCases()](./api-extractor-test-05.docclass1.interestingedgecases.md)</p> |  | <p>Example: "<!-- -->{ \\<!-- -->"maxItemsToShow<!-- -->\\<!-- -->": 123 }<!-- -->"</p><p>The regular expression used to validate the constraints is /^\[a-zA-Z0-9<!-- -->\\<!-- -->-\_\]+$/</p> |

build-tests/api-extractor-test-05/etc/yaml/api-extractor-test-05/docclass1.yml

@@ -10,6 +10,7 @@ items:
     type: class
     package: api-extractor-test-05
     children:
+      - api-extractor-test-05.DocClass1.deprecatedExample
       - api-extractor-test-05.DocClass1.exampleFunction
       - api-extractor-test-05.DocClass1.exampleFunction_1
       - api-extractor-test-05.DocClass1.interestingEdgeCases
@@ -18,6 +19,20 @@ items:
       - api-extractor-test-05.DocClass1.regularProperty
       - api-extractor-test-05.DocClass1.sumWithExample
       - api-extractor-test-05.DocClass1.tableExample
+  - uid: api-extractor-test-05.DocClass1.deprecatedExample
+    deprecated:
+      content: Use `otherThing()` instead.
+    name: deprecatedExample()
+    fullName: api-extractor-test-05.DocClass1.deprecatedExample
+    langs:
+      - typeScript
+    type: method
+    syntax:
+      content: 'deprecatedExample(): void;'
+      return:
+        type:
+          - void
+        description: ''
   - uid: api-extractor-test-05.DocClass1.exampleFunction
     summary: This is an overloaded function.
     name: 'exampleFunction(a, b)'

build-tests/api-extractor-test-05/src/DocClass1.ts

@@ -76,6 +76,12 @@ export class DocClass1 {
   interestingEdgeCases(): void {
   }
 
+  /**
+   * @deprecated Use `otherThing()` instead.
+   */
+  public deprecatedExample(): void {
+  }
+
   /**
    * Returns the sum of two numbers.
    *