Skip to content

Commit 6c28ce5

Browse files
guoyunheguoyunhe
authored
Merge branch 'microsoft:main' into patch-1
2 parents 594ee16 + f6cf434 commit 6c28ce5

180 files changed

Lines changed: 1648 additions & 417 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/api-documenter/CHANGELOG.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,29 @@
11
{
22
"name": "@microsoft/api-documenter",
33
"entries": [
4+
{
5+
"version": "7.18.0",
6+
"tag": "@microsoft/api-documenter_v7.18.0",
7+
"date": "Thu, 30 Jun 2022 04:48:53 GMT",
8+
"comments": {
9+
"minor": [
10+
{
11+
"comment": "Show protected and readonly modifiers for relevant API items"
12+
}
13+
],
14+
"dependency": [
15+
{
16+
"comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.21.0`"
17+
},
18+
{
19+
"comment": "Updating dependency \"@rushstack/heft\" to `0.46.1`"
20+
},
21+
{
22+
"comment": "Updating dependency \"@rushstack/heft-node-rig\" to `1.9.17`"
23+
}
24+
]
25+
}
26+
},
427
{
528
"version": "7.17.26",
629
"tag": "@microsoft/api-documenter_v7.17.26",

‎apps/api-documenter/CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Change Log - @microsoft/api-documenter
22

3-
This log was last generated on Tue, 28 Jun 2022 22:47:13 GMT and should not be manually modified.
3+
This log was last generated on Thu, 30 Jun 2022 04:48:53 GMT and should not be manually modified.
4+
5+
## 7.18.0
6+
Thu, 30 Jun 2022 04:48:53 GMT
7+
8+
### Minor changes
9+
10+
- Show protected and readonly modifiers for relevant API items
411

512
## 7.17.26
613
Tue, 28 Jun 2022 22:47:13 GMT

‎apps/api-documenter/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@microsoft/api-documenter",
3-
"version": "7.17.26",
3+
"version": "7.18.0",
44
"description": "Read JSON files from api-extractor, generate documentation pages",
55
"repository": {
66
"type": "git",

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

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,9 @@ import {
4141
ApiTypeAlias,
4242
ExcerptToken,
4343
ApiOptionalMixin,
44-
ApiInitializerMixin
44+
ApiInitializerMixin,
45+
ApiProtectedMixin,
46+
ApiReadonlyMixin
4547
} from '@microsoft/api-extractor-model';
4648

4749
import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -755,12 +757,12 @@ export class MarkdownDocumenter {
755757

756758
const eventsTable: DocTable = new DocTable({
757759
configuration,
758-
headerTitles: ['Property', 'Type', 'Description']
760+
headerTitles: ['Property', 'Modifiers', 'Type', 'Description']
759761
});
760762

761763
const propertiesTable: DocTable = new DocTable({
762764
configuration,
763-
headerTitles: ['Property', 'Type', 'Description']
765+
headerTitles: ['Property', 'Modifiers', 'Type', 'Description']
764766
});
765767

766768
const methodsTable: DocTable = new DocTable({
@@ -787,6 +789,7 @@ export class MarkdownDocumenter {
787789
eventsTable.addRow(
788790
new DocTableRow({ configuration }, [
789791
this._createTitleCell(apiMember),
792+
this._createModifiersCell(apiMember),
790793
this._createPropertyTypeCell(apiMember),
791794
this._createDescriptionCell(apiMember)
792795
])
@@ -795,6 +798,7 @@ export class MarkdownDocumenter {
795798
propertiesTable.addRow(
796799
new DocTableRow({ configuration }, [
797800
this._createTitleCell(apiMember),
801+
this._createModifiersCell(apiMember),
798802
this._createPropertyTypeCell(apiMember),
799803
this._createDescriptionCell(apiMember)
800804
])
@@ -1007,9 +1011,27 @@ export class MarkdownDocumenter {
10071011

10081012
const section: DocSection = new DocSection({ configuration });
10091013

1014+
if (ApiProtectedMixin.isBaseClassOf(apiItem)) {
1015+
if (apiItem.isProtected) {
1016+
section.appendNode(
1017+
new DocParagraph({ configuration }, [new DocCodeSpan({ configuration, code: 'protected' })])
1018+
);
1019+
}
1020+
}
1021+
1022+
if (ApiReadonlyMixin.isBaseClassOf(apiItem)) {
1023+
if (apiItem.isReadonly) {
1024+
section.appendNode(
1025+
new DocParagraph({ configuration }, [new DocCodeSpan({ configuration, code: 'readonly' })])
1026+
);
1027+
}
1028+
}
1029+
10101030
if (ApiStaticMixin.isBaseClassOf(apiItem)) {
10111031
if (apiItem.isStatic) {
1012-
section.appendNodeInParagraph(new DocCodeSpan({ configuration, code: 'static' }));
1032+
section.appendNode(
1033+
new DocParagraph({ configuration }, [new DocCodeSpan({ configuration, code: 'static' })])
1034+
);
10131035
}
10141036
}
10151037

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
147147
break;
148148
}
149149
default:
150-
super.writeNode(docNode, context, false);
150+
super.writeNode(docNode, context, docNodeSiblings);
151151
}
152152
}
153153

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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,13 @@ export class MarkdownEmitter {
141141
const trimmedParagraph: DocParagraph = DocNodeTransforms.trimSpacesInParagraph(docParagraph);
142142
if (context.insideTable) {
143143
if (docNodeSiblings) {
144-
writer.write('<p>');
145-
this.writeNodes(trimmedParagraph.nodes, context);
146-
writer.write('</p>');
144+
// This tentative write is necessary to avoid writing empty paragraph tags (i.e. `<p></p>`). At the
145+
// time this code runs, we do not know whether the `writeNodes` call below will actually write
146+
// anything. Thus, we want to only write a `<p>` tag (as well as eventually a corresponding
147+
// `</p>` tag) if something ends up being written within the tags.
148+
writer.writeTentative('<p>', '</p>', () => {
149+
this.writeNodes(trimmedParagraph.nodes, context);
150+
});
147151
} else {
148152
// Special case: If we are the only element inside this table cell, then we can omit the <p></p> container.
149153
this.writeNodes(trimmedParagraph.nodes, context);

‎apps/api-documenter/src/utils/IndentedWriter.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ export class IndentedWriter {
4646
private readonly _indentStack: string[];
4747
private _indentText: string;
4848

49+
private _beforeStack: string[];
50+
private _isWritingBeforeStack: boolean;
51+
4952
public constructor(builder?: IStringBuilder) {
5053
this._builder = builder === undefined ? new StringBuilder() : builder;
5154

@@ -55,6 +58,9 @@ export class IndentedWriter {
5558

5659
this._indentStack = [];
5760
this._indentText = '';
61+
62+
this._beforeStack = [];
63+
this._isWritingBeforeStack = false;
5864
}
5965

6066
/**
@@ -149,6 +155,30 @@ export class IndentedWriter {
149155
return '';
150156
}
151157

158+
/**
159+
* Writes `before` and `after` messages if and only if `mayWrite` writes anything.
160+
*
161+
* If `mayWrite` writes "CONTENT", this method will write "<before>CONTENT<after>".
162+
* If `mayWrite` writes nothing, this method will write nothing.
163+
*/
164+
public writeTentative(before: string, after: string, mayWrite: () => void): void {
165+
this._beforeStack.push(before);
166+
167+
// If this function writes anything, then _all_ messages in the "before stack" will also be
168+
// written. This means that the stack will be empty (as when we write a message from the stack,
169+
// we remove it from the stack).
170+
mayWrite();
171+
172+
// If the stack is not empty, it means that `mayWrite` didn't write anything. Pop the last-
173+
// added message from the stack, we'll never write it. Otherwise, if the stack is empty, then
174+
// write the "after" message.
175+
if (this._beforeStack.length > 0) {
176+
this._beforeStack.pop();
177+
} else {
178+
this.write(after);
179+
}
180+
}
181+
152182
/**
153183
* Writes some text to the internal string buffer, applying indentation according
154184
* to the current indentation level. If the string contains multiple newlines,
@@ -159,6 +189,10 @@ export class IndentedWriter {
159189
return;
160190
}
161191

192+
if (!this._isWritingBeforeStack) {
193+
this._writeBeforeStack();
194+
}
195+
162196
// If there are no newline characters, then append the string verbatim
163197
if (!/[\r\n]/.test(message)) {
164198
this._writeLinePart(message);
@@ -186,7 +220,10 @@ export class IndentedWriter {
186220
public writeLine(message: string = ''): void {
187221
if (message.length > 0) {
188222
this.write(message);
223+
} else if (!this._isWritingBeforeStack) {
224+
this._writeBeforeStack();
189225
}
226+
190227
this._writeNewLine();
191228
}
192229

@@ -218,6 +255,21 @@ export class IndentedWriter {
218255
this._builder.append(s);
219256
}
220257

258+
/**
259+
* Writes all messages in our before stack, processing them in FIFO order. This stack is
260+
* populated by the `writeTentative` method.
261+
*/
262+
private _writeBeforeStack(): void {
263+
this._isWritingBeforeStack = true;
264+
265+
for (const message of this._beforeStack) {
266+
this.write(message);
267+
}
268+
269+
this._isWritingBeforeStack = false;
270+
this._beforeStack = [];
271+
}
272+
221273
private _updateIndentText(): void {
222274
this._indentText = this._indentStack.join('');
223275
}

‎apps/api-extractor/CHANGELOG.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,23 @@
11
{
22
"name": "@microsoft/api-extractor",
33
"entries": [
4+
{
5+
"version": "7.28.2",
6+
"tag": "@microsoft/api-extractor_v7.28.2",
7+
"date": "Thu, 30 Jun 2022 04:48:53 GMT",
8+
"comments": {
9+
"patch": [
10+
{
11+
"comment": "Improve logic that determines whether an API item is readonly"
12+
}
13+
],
14+
"dependency": [
15+
{
16+
"comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.21.0`"
17+
}
18+
]
19+
}
20+
},
421
{
522
"version": "7.28.1",
623
"tag": "@microsoft/api-extractor_v7.28.1",

‎apps/api-extractor/CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Change Log - @microsoft/api-extractor
22

3-
This log was last generated on Tue, 28 Jun 2022 22:47:13 GMT and should not be manually modified.
3+
This log was last generated on Thu, 30 Jun 2022 04:48:53 GMT and should not be manually modified.
4+
5+
## 7.28.2
6+
Thu, 30 Jun 2022 04:48:53 GMT
7+
8+
### Patches
9+
10+
- Improve logic that determines whether an API item is readonly
411

512
## 7.28.1
613
Tue, 28 Jun 2022 22:47:13 GMT

‎apps/api-extractor/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@microsoft/api-extractor",
3-
"version": "7.28.1",
3+
"version": "7.28.2",
44
"description": "Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups",
55
"keywords": [
66
"typescript",

0 commit comments

Comments
 (0)