Skip to content

Commit 8fc4e1c

Browse files
pgonzalpgonzal
committed
MarkdownDocumenter.ts is now more or less working using TSDoc instead of Markup
1 parent 2add3cc commit 8fc4e1c

File tree

10 files changed

+681
-346
lines changed

10 files changed

+681
-346
lines changed

‎apps/api-documenter/src/nodes/CustomDocNodeKind.ts‎

Lines changed: 51 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,59 @@
1+
import { TSDocConfiguration, DocNode, DocNodeKind } from '@microsoft/tsdoc';
2+
import { DocEmphasisSpan } from './DocEmphasisSpan';
3+
import { DocHeading } from './DocHeading';
4+
import { DocNoteBox } from './DocNoteBox';
5+
import { DocTable } from './DocTable';
6+
import { DocTableCell } from './DocTableCell';
7+
import { DocTableRow } from './DocTableRow';
8+
19
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
210
// See LICENSE in the project root for license information.
311

412
/**
513
* Identifies custom subclasses of {@link DocNode}.
614
*/
715
export const enum CustomDocNodeKind {
8-
Heading = '@microsoft/api-documenter#Heading',
9-
NoteBox = '@microsoft/api-documenter#NoteBox',
10-
Table = '@microsoft/api-documenter#Table',
11-
TableCell = '@microsoft/api-documenter#TableCell',
12-
TableRow = '@microsoft/api-documenter#TableRow'
16+
EmphasisSpan = 'EmphasisSpan',
17+
Heading = 'Heading',
18+
NoteBox = 'NoteBox',
19+
Table = 'Table',
20+
TableCell = 'TableCell',
21+
TableRow = 'TableRow'
22+
}
23+
24+
export class CustomDocNodes {
25+
private static _configuration: TSDocConfiguration | undefined;
26+
27+
public static get configuration(): TSDocConfiguration {
28+
if (CustomDocNodes._configuration === undefined) {
29+
const configuration: TSDocConfiguration = new TSDocConfiguration();
30+
31+
configuration.docNodeManager.registerDocNodes('@micrososft/api-documenter', [
32+
{ docNodeKind: CustomDocNodeKind.EmphasisSpan, constructor: DocEmphasisSpan },
33+
{ docNodeKind: CustomDocNodeKind.Heading, constructor: DocHeading },
34+
{ docNodeKind: CustomDocNodeKind.NoteBox, constructor: DocNoteBox },
35+
{ docNodeKind: CustomDocNodeKind.Table, constructor: DocTable },
36+
{ docNodeKind: CustomDocNodeKind.TableCell, constructor: DocTableCell },
37+
{ docNodeKind: CustomDocNodeKind.TableRow, constructor: DocTableRow }
38+
]);
39+
40+
configuration.docNodeManager.registerAllowableChildren(CustomDocNodeKind.EmphasisSpan, [
41+
DocNodeKind.PlainText,
42+
DocNodeKind.SoftBreak
43+
]);
44+
45+
configuration.docNodeManager.registerAllowableChildren(DocNodeKind.Section, [
46+
CustomDocNodeKind.Heading,
47+
CustomDocNodeKind.NoteBox,
48+
CustomDocNodeKind.Table
49+
]);
50+
51+
configuration.docNodeManager.registerAllowableChildren(DocNodeKind.Paragraph, [
52+
CustomDocNodeKind.EmphasisSpan
53+
]);
54+
55+
CustomDocNodes._configuration = configuration;
56+
}
57+
return CustomDocNodes._configuration;
58+
}
1359
}

‎apps/api-documenter/src/nodes/DocEmphasisSpan.ts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
2+
// See LICENSE in the project root for license information.
3+
4+
import {
5+
DocNode,
6+
DocNodeContainer,
7+
IDocNodeContainerParameters
8+
} from '@microsoft/tsdoc';
9+
import { CustomDocNodeKind } from './CustomDocNodeKind';
10+
11+
/**
12+
* Constructor parameters for {@link DocEmphasisSpan}.
13+
*/
14+
export interface IDocEmphasisSpanParameters extends IDocNodeContainerParameters {
15+
bold?: boolean;
16+
italic?: boolean;
17+
}
18+
19+
/**
20+
* Represents a span of text that is styled with CommonMark emphasis (italics), strong emphasis (boldface),
21+
* or both.
22+
*/
23+
export class DocEmphasisSpan extends DocNodeContainer {
24+
public readonly bold: boolean;
25+
public readonly italic: boolean;
26+
27+
public constructor(parameters: IDocEmphasisSpanParameters, children?: DocNode[]) {
28+
super(parameters, children);
29+
this.bold = !!parameters.bold;
30+
this.italic = !!parameters.italic;
31+
}
32+
33+
/** @override */
34+
public get kind(): string {
35+
return CustomDocNodeKind.EmphasisSpan;
36+
}
37+
}

‎apps/api-documenter/src/nodes/DocHeading.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,9 @@ export interface IDocHeadingParameters extends IDocNodeParameters {
1616
}
1717

1818
/**
19-
* Represents a heading such as an HTML `<h1>` element.
19+
* Represents table, similar to an HTML `<h1>` or `<h2>` element.
2020
*/
2121
export class DocHeading extends DocNode {
22-
/** {@inheritDoc} */
23-
public readonly kind: CustomDocNodeKind = CustomDocNodeKind.Heading;
24-
2522
public readonly title: string;
2623
public readonly level: number;
2724

@@ -33,5 +30,14 @@ export class DocHeading extends DocNode {
3330
super(parameters);
3431
this.title = parameters.title;
3532
this.level = parameters.level !== undefined ? parameters.level : 1;
33+
34+
if (this.level < 1 || this.level > 5) {
35+
throw new Error('IDocHeadingParameters.level must be a number between 1 and 5');
36+
}
37+
}
38+
39+
/** @override */
40+
public get kind(): string {
41+
return CustomDocNodeKind.Heading;
3642
}
3743
}

‎apps/api-documenter/src/nodes/DocNoteBox.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,19 @@ export interface IDocNoteBoxParameters extends IDocNodeParameters {
1515
}
1616

1717
/**
18-
* Represents a heading such as an HTML `<h1>` element.
18+
* Represents a note box, which is typically displayed as a bordered box containing informational text.
1919
*/
2020
export class DocNoteBox extends DocNode {
21-
/** {@inheritDoc} */
22-
public readonly kind: CustomDocNodeKind = CustomDocNodeKind.NoteBox;
23-
2421
public readonly content: DocSection;
2522

2623
public constructor(parameters: IDocNoteBoxParameters) {
2724
super(parameters);
28-
this.content = new DocSection();
25+
this.content = new DocSection({ configuration: this.configuration });
26+
}
27+
28+
/** @override */
29+
public get kind(): string {
30+
return CustomDocNodeKind.NoteBox;
2931
}
3032

3133
/** @override */

‎apps/api-documenter/src/nodes/DocTable.ts‎

Lines changed: 50 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,72 @@ import {
88
} from '@microsoft/tsdoc';
99
import { CustomDocNodeKind } from './CustomDocNodeKind';
1010
import { DocTableRow } from './DocTableRow';
11+
import { DocTableCell } from './DocTableCell';
1112

1213
/**
13-
* Represents a heading such as an HTML `<h1>` element.
14+
* Constructor parameters for {@link DocTable}.
1415
*/
15-
export class DocTable extends DocNode {
16-
/** {@inheritDoc} */
17-
public readonly kind: CustomDocNodeKind = CustomDocNodeKind.Table;
16+
export interface IDocTableParameters extends IDocNodeParameters {
17+
headerCells?: ReadonlyArray<DocTableCell>;
18+
headerTitles?: string[];
19+
}
1820

21+
/**
22+
* Represents table, similar to an HTML `<table>` element.
23+
*/
24+
export class DocTable extends DocNode {
1925
public readonly header: DocTableRow;
2026

2127
private _rows: DocTableRow[];
2228

23-
public constructor() {
24-
super({});
29+
public constructor(parameters: IDocTableParameters, rows?: ReadonlyArray<DocTableRow>) {
30+
super(parameters);
2531

26-
this.header = new DocTableRow();
32+
this.header = new DocTableRow({ configuration: this.configuration });
2733
this._rows = [];
34+
35+
if (parameters) {
36+
if (parameters.headerTitles) {
37+
if (parameters.headerCells) {
38+
throw new Error('IDocTableParameters.headerCells and IDocTableParameters.headerTitles'
39+
+ ' cannot both be specified');
40+
}
41+
for (const cellText of parameters.headerTitles) {
42+
this.header.addPlainTextCell(cellText);
43+
}
44+
} else if (parameters.headerCells) {
45+
for (const cell of parameters.headerCells) {
46+
this.header.addCell(cell);
47+
}
48+
}
49+
}
50+
51+
if (rows) {
52+
for (const row of rows) {
53+
this.addRow(row);
54+
}
55+
}
56+
}
57+
58+
/** @override */
59+
public get kind(): string {
60+
return CustomDocNodeKind.Table;
2861
}
2962

3063
public get rows(): ReadonlyArray<DocTableRow> {
3164
return this._rows;
3265
}
3366

67+
public addRow(row: DocTableRow): void {
68+
this._rows.push(row);
69+
}
70+
71+
public createAndAddRow(): DocTableRow {
72+
const row: DocTableRow = new DocTableRow({ configuration: this.configuration });
73+
this.addRow(row);
74+
return row;
75+
}
76+
3477
/** @override */
3578
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined> {
3679
return [this.header, ...this._rows];

‎apps/api-documenter/src/nodes/DocTableCell.ts‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,25 @@ import {
99
import { CustomDocNodeKind } from './CustomDocNodeKind';
1010

1111
/**
12-
* Represents a heading such as an HTML `<h1>` element.
12+
* Constructor parameters for {@link DocTableCell}.
1313
*/
14-
export class DocTableCell extends DocNode {
15-
/** {@inheritDoc} */
16-
public readonly kind: CustomDocNodeKind = CustomDocNodeKind.TableCell;
14+
export interface IDocTableCellParameters extends IDocNodeParameters {
15+
}
1716

17+
/**
18+
* Represents table cell, similar to an HTML `<td>` element.
19+
*/
20+
export class DocTableCell extends DocNode {
1821
public readonly content: DocSection;
1922

20-
public constructor() {
21-
super({});
23+
public constructor(parameters: IDocTableCellParameters, sectionChildNodes?: ReadonlyArray<DocNode>) {
24+
super(parameters);
25+
26+
this.content = new DocSection({ configuration: this.configuration }, sectionChildNodes);
27+
}
2228

23-
this.content = new DocSection();
29+
/** @override */
30+
public get kind(): string {
31+
return CustomDocNodeKind.TableCell;
2432
}
2533
}

‎apps/api-documenter/src/nodes/DocTableRow.ts‎

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,64 @@
44
import {
55
IDocNodeParameters,
66
DocNode,
7-
DocSection
7+
DocSection,
8+
DocPlainText
89
} from '@microsoft/tsdoc';
910
import { CustomDocNodeKind } from './CustomDocNodeKind';
1011
import { DocTableCell } from './DocTableCell';
12+
import { DocTable } from './DocTable';
1113

1214
/**
13-
* Represents a heading such as an HTML `<h1>` element.
15+
* Constructor parameters for {@link DocTableRow}.
16+
*/
17+
export interface IDocTableRowParameters extends IDocNodeParameters {
18+
}
19+
20+
/**
21+
* Represents table row, similar to an HTML `<tr>` element.
1422
*/
1523
export class DocTableRow extends DocNode {
16-
/** {@inheritDoc} */
17-
public readonly kind: CustomDocNodeKind = CustomDocNodeKind.TableRow;
24+
private readonly _cells: DocTableCell[];
1825

19-
private _cells: DocTableCell[];
26+
public constructor(parameters: IDocTableRowParameters, cells?: ReadonlyArray<DocTableCell>) {
27+
super(parameters);
2028

21-
public constructor() {
22-
super({});
29+
this._cells = [];
30+
if (cells) {
31+
for (const cell of cells) {
32+
this.addCell(cell);
33+
}
34+
}
35+
}
36+
37+
/** @override */
38+
public get kind(): string {
39+
return CustomDocNodeKind.TableRow;
2340
}
2441

2542
public get cells(): ReadonlyArray<DocTableCell> {
2643
return this._cells;
2744
}
2845

46+
public addCell(cell: DocTableCell): void {
47+
this._cells.push(cell);
48+
}
49+
50+
public createAndAddCell(): DocTableCell {
51+
const newCell: DocTableCell = new DocTableCell({ configuration: this.configuration });
52+
this.addCell(newCell);
53+
return newCell;
54+
}
55+
56+
public addPlainTextCell(cellContent: string): DocTableCell {
57+
const cell: DocTableCell = this.createAndAddCell();
58+
cell.content.appendNodeInParagraph(new DocPlainText({
59+
configuration: this.configuration,
60+
text: cellContent
61+
}));
62+
return cell;
63+
}
64+
2965
/** @override */
3066
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined> {
3167
return this._cells;

0 commit comments

Comments
 (0)