Skip to content

Commit fc3ff0e

Browse files
pgonzalpgonzal
committed
MarkdownDocumenter now writes @deprecated warnings
1 parent af43975 commit fc3ff0e

File tree

9 files changed

+95
-10
lines changed

9 files changed

+95
-10
lines changed

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

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ import {
1919
DocCodeSpan,
2020
DocFencedCode,
2121
StandardTags,
22-
DocBlock
22+
DocBlock,
23+
DocComment
2324
} from '@microsoft/tsdoc';
2425
import {
2526
ApiModel,
@@ -117,8 +118,27 @@ export class MarkdownDocumenter {
117118
}
118119

119120
if (apiItem instanceof ApiDocumentedItem) {
120-
if (apiItem.tsdocComment) {
121-
this._appendSection(output, apiItem.tsdocComment.summarySection);
121+
const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
122+
123+
if (tsdocComment) {
124+
125+
if (tsdocComment.deprecatedBlock) {
126+
output.appendNode(
127+
new DocNoteBox({ configuration: this._tsdocConfiguration },
128+
[
129+
new DocParagraph({ configuration: this._tsdocConfiguration }, [
130+
new DocPlainText({
131+
configuration: this._tsdocConfiguration,
132+
text: 'Warning: This API is now obsolete. '
133+
})
134+
]),
135+
...tsdocComment.deprecatedBlock.content.nodes
136+
]
137+
)
138+
);
139+
}
140+
141+
this._appendSection(output, tsdocComment.summarySection);
122142
}
123143
}
124144

@@ -161,15 +181,17 @@ export class MarkdownDocumenter {
161181
}
162182

163183
if (apiItem instanceof ApiDocumentedItem) {
164-
if (apiItem.tsdocComment) {
184+
const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
185+
186+
if (tsdocComment) {
165187
// Write the @remarks block
166-
if (apiItem.tsdocComment.remarksBlock) {
188+
if (tsdocComment.remarksBlock) {
167189
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Remarks' }));
168-
this._appendSection(output, apiItem.tsdocComment.remarksBlock.content);
190+
this._appendSection(output, tsdocComment.remarksBlock.content);
169191
}
170192

171193
// Write the @example blocks
172-
const exampleBlocks: DocBlock[] = apiItem.tsdocComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
194+
const exampleBlocks: DocBlock[] = tsdocComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
173195
=== StandardTags.example.tagNameWithUpperCase);
174196

175197
let exampleNumber: number = 1;

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,10 +68,14 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
6868
case CustomDocNodeKind.NoteBox: {
6969
const docNoteBox: DocNoteBox = docNode as DocNoteBox;
7070
writer.ensureNewLine();
71-
writer.write('> ');
72-
// TODO: Handle newlines
71+
72+
writer.increaseIndent('> ');
73+
7374
this.writeNode(docNoteBox.content, context);
7475
writer.ensureNewLine();
76+
77+
writer.decreaseIndent();
78+
7579
writer.writeLine();
7680
break;
7781
}

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

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,10 @@ export class IndentedWriter {
157157
* each line will be indented separately.
158158
*/
159159
public write(message: string): void {
160+
if (message.length === 0) {
161+
return;
162+
}
163+
160164
// If there are no newline characters, then append the string verbatim
161165
if (!/[\r\n]/.test(message)) {
162166
this._writeLinePart(message);
@@ -182,7 +186,9 @@ export class IndentedWriter {
182186
* Indentation is applied following the semantics of IndentedWriter.write().
183187
*/
184188
public writeLine(message: string = ''): void {
185-
this.write(message);
189+
if (message.length > 0) {
190+
this.write(message);
191+
}
186192
this._writeNewLine();
187193
}
188194

@@ -200,6 +206,10 @@ export class IndentedWriter {
200206
}
201207

202208
private _writeNewLine(): void {
209+
if (this._atStartOfLine && this._indentText.length > 0) {
210+
this._write(this._indentText);
211+
}
212+
203213
this._write('\n');
204214
this._atStartOfLine = true;
205215
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ test('02 Indent something', () => {
2626
indentedWriter.decreaseIndent();
2727
indentedWriter.writeLine('e');
2828

29+
indentedWriter.increaseIndent('>>> ');
30+
indentedWriter.writeLine();
31+
indentedWriter.writeLine();
32+
indentedWriter.writeLine('g');
33+
indentedWriter.decreaseIndent();
34+
2935
expect(indentedWriter.toString()).toMatchSnapshot();
3036
});
3137

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ exports[`02 Indent something 1`] = `
1111
"abc
1212
d
1313
e
14+
>>>
15+
>>>
16+
>>> g
1417
"
1518
`;
1619

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[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)
2+
3+
## DocClass1.deprecatedExample() method
4+
5+
> Warning: This API is now obsolete.
6+
>
7+
> Use `otherThing()` instead.
8+
>
9+
10+
<b>Signature:</b>
11+
12+
```typescript
13+
deprecatedExample(): void;
14+
```
15+
<b>Returns:</b>
16+
17+
`void`
18+

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ export declare class DocClass1
2727

2828
| <p>Method</p> | <p>Modifiers</p> | <p>Description</p> |
2929
| --- | --- | --- |
30+
| <p>[deprecatedExample()](./api-extractor-test-05.docclass1.deprecatedexample.md)</p> | | |
3031
| <p>[exampleFunction(a, b)](./api-extractor-test-05.docclass1.examplefunction.md)</p> | | <p>This is an overloaded function.</p> |
3132
| <p>[exampleFunction(x)](./api-extractor-test-05.docclass1.examplefunction_1.md)</p> | | <p>This is also an overloaded function.</p> |
3233
| <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‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ items:
1010
type: class
1111
package: api-extractor-test-05
1212
children:
13+
- api-extractor-test-05.DocClass1.deprecatedExample
1314
- api-extractor-test-05.DocClass1.exampleFunction
1415
- api-extractor-test-05.DocClass1.exampleFunction_1
1516
- api-extractor-test-05.DocClass1.interestingEdgeCases
@@ -18,6 +19,20 @@ items:
1819
- api-extractor-test-05.DocClass1.regularProperty
1920
- api-extractor-test-05.DocClass1.sumWithExample
2021
- api-extractor-test-05.DocClass1.tableExample
22+
- uid: api-extractor-test-05.DocClass1.deprecatedExample
23+
deprecated:
24+
content: Use `otherThing()` instead.
25+
name: deprecatedExample()
26+
fullName: api-extractor-test-05.DocClass1.deprecatedExample
27+
langs:
28+
- typeScript
29+
type: method
30+
syntax:
31+
content: 'deprecatedExample(): void;'
32+
return:
33+
type:
34+
- void
35+
description: ''
2136
- uid: api-extractor-test-05.DocClass1.exampleFunction
2237
summary: This is an overloaded function.
2338
name: 'exampleFunction(a, b)'

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,12 @@ export class DocClass1 {
7676
interestingEdgeCases(): void {
7777
}
7878

79+
/**
80+
* @deprecated Use `otherThing()` instead.
81+
*/
82+
public deprecatedExample(): void {
83+
}
84+
7985
/**
8086
* Returns the sum of two numbers.
8187
*

0 commit comments

Comments
 (0)