8000 tmp · dotnet/api-docs-sync@6ce8501 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6ce8501

Browse files
carlossanlopcarlossanlop
committed
tmp
1 parent e402e46 commit 6ce8501

File tree

1 file changed

+104
-77
lines changed

1 file changed

+104
-77
lines changed

‎src/PortToTripleSlash/src/libraries/RoslynTripleSlash/DocumentationUpdater.cs

Lines changed: 104 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
using Microsoft.CodeAnalysis;
1010
using Microsoft.CodeAnalysis.CSharp;
1111
using Microsoft.CodeAnalysis.CSharp.Syntax;
12+
using static System.Net.Mime.MediaTypeNames;
1213

1314
namespace ApiDocsSync.PortToTripleSlash.Roslyn;
1415

@@ -33,7 +34,7 @@ public DocumentationUpdater(Configuration config, IDocsAPI api, SyntaxTrivia? in
3334

3435
public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax> originalDocumentation)
3536
{
36-
SyntaxList<XmlNodeSyntax> docsNodes = SyntaxFactory.List<XmlNodeSyntax>();
37+
List<XmlNodeSyntax> docsNodes = [];
3738

3839
// Preserve the order in which each API element is looked for below
3940

@@ -43,7 +44,7 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
4344
}
4445
else if (TryGet("summary") is XmlNodeSyntax existingSummary)
4546
{
46-
docsNodes.Add(existingSummary);
47+
docsNodes.AddRange(RegeneraGetFullTripleSlashXmlSyntaxNodeteExistingNode(existingSummary));
4748
}
4849

4950
foreach (DocsTypeParam typeParam in _api.TypeParams)
@@ -54,7 +55,7 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
5455
}
5556
else if (TryGet("typeparam", "name", typeParam.Value) is XmlNodeSyntax existingTypeParam)
5657
{
57-
docsNodes.Add(existingTypeParam);
58+
docsNodes.AddRange(GetFullTripleSlashXmlSyntaxNode(existingTypeParam));
5859

5960
}
6061
}
@@ -67,7 +68,7 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
6768
}
6869
else if (TryGet("param", "name", param.Value) is XmlNodeSyntax existingParam)
6970
{
70-
docsNodes.Add(existingParam);
71+
docsNodes.AddRange(GetFullTripleSlashXmlSyntaxNode(existingParam));
7172

7273
}
7374
}
@@ -78,16 +79,19 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
7879
}
7980
else if (TryGet("returns") is XmlNodeSyntax existingReturns)
8081
{
81-
docsNodes.Add(existingReturns);
82+
docsNodes.AddRange(GetFullTripleSlashXmlSyntaxNode(existingReturns));
8283
}
8384

84-
if (!_config.SkipRemarks && !_api.Remarks.IsDocsEmpty())
85+
if (!_config.SkipRemarks)
8586
{
86-
docsNodes.AddRange(GetRemarksNodes());
87-
}
88-
else if (TryGet("remarks") is XmlNodeSyntax existingRemarks)
89-
{
90-
docsNodes.Add(existingRemarks);
87+
if (!_api.Remarks.IsDocsEmpty())
88+
{
89+
docsNodes.AddRange(GetRemarksNodes());
90+
}
91+
else if (TryGet("remarks") is XmlNodeSyntax existingRemarks)
92+
{
93+
docsNodes.AddRange(GetFullTripleSlashXmlSyntaxNode(existingRemarks));
94+
}
9195
}
9296

9397
foreach (DocsException exception in _api.Exceptions)
@@ -98,14 +102,14 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
98102
}
99103
else if (TryGet("exception", "cref", exception.Value) is XmlNodeSyntax existingException)
100104
{
101-
docsNodes.Add(existingException);
105+
docsNodes.AddRange(GetFullTripleSlashXmlSyntaxNode(existingExceptio 10000 n));
102106

103107
}
104108
}
105109

106110
return SyntaxFactory.DocumentationCommentTrivia(
107111
SyntaxKind.SingleLineDocumentationCommentTrivia,
108-
docsNodes);
112+
SyntaxFactory.List(docsNodes));
109113

110114
XmlNodeSyntax? TryGet(string tagName, string? attributeName = null, string? attributeValue = null)
111115
{
@@ -115,19 +119,20 @@ public DocumentationCommentTriviaSyntax GetUpdatedDocs(SyntaxList<XmlNodeSyntax>
115119

116120
public DocumentationCommentTriviaSyntax GetNewDocs()
117121
{
118-
SyntaxList<XmlNodeSyntax> docsNodes = SyntaxFactory.List<XmlNodeSyntax>();
119-
120-
// Preserve the order
121-
docsNodes.AddRange(GetSummaryNodes());
122-
docsNodes.AddRange(GetTypeParamNodes());
123-
docsNodes.AddRange(GetParamNodes());
124-
docsNodes.AddRange(GetReturnsNodes());
125-
docsNodes.AddRange(GetRemarksNodes());
126-
docsNodes.AddRange(GetExceptionNodes());
122+
List<XmlNodeSyntax> docsNodes =
123+
[
124+
// Preserve the order
125+
.. GetSummaryNodes(),
126+
.. GetTypeParamNodes(),
127+
.. GetParamNodes(),
128+
.. GetReturnsNodes(),
129+
.. GetRemarksNodes(),
130+
.. GetExceptionNodes(),
131+
];
127132

128133
return SyntaxFactory.DocumentationCommentTrivia(
129134
SyntaxKind.SingleLineDocumentationCommentTrivia,
130-
docsNodes);
135+
SyntaxFactory.List(docsNodes));
131136
}
132137

133138
private XmlNodeSyntax[] GetSummaryNodes()
@@ -137,16 +142,16 @@ private XmlNodeSyntax[] GetSummaryNodes()
137142
return [];
138143
}
139144

140-
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
145+
List<XmlNodeSyntax> internalTextNodes = new();
141146
foreach (string line in _api.Summary.Split(_NewLineSeparators, _NewLineSplitOptions))
142147
{
143-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
148+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
144149
}
145150

146151
return [
147152
GetTripleSlashTextSyntaxNode(),
148-
SyntaxFactory.XmlSummaryElement(internalTextNodes),
149-
GetNewLineTextSyntaxNode(),
153+
SyntaxFactory.XmlSummaryElement(internalTextNodes.ToArray()).WithEndTag(endTag), // TODO
154+
GetNewLineTextSyntaxNode()
150155
];
151156
}
152157

@@ -157,7 +162,7 @@ private XmlNodeSyntax[] GetTypeParamNodes()
157162
return [];
158163
}
159164

160-
SyntaxList<XmlNodeSyntax> typeParamNodes = SyntaxFactory.List<XmlNodeSyntax>();
165+
List<XmlNodeSyntax> typeParamNodes = new();
161166
foreach (DocsTypeParam typeParam in _api.TypeParams)
162167
{
163168
typeParamNodes.AddRange(GetTypeParamNode(typeParam));
@@ -168,17 +173,14 @@ private XmlNodeSyntax[] GetTypeParamNodes()
168173

169174
private XmlNodeSyntax[] GetTypeParamNode(DocsTypeParam typeParam)
170175
{
171-
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
176+
List<XmlNodeSyntax> internalTextNodes = new();
172177
foreach (string line in typeParam.Value.Split(_NewLineSeparators, _NewLineSplitOptions))
173178
{
174-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
179+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
175180
}
176181

177-
return [
178-
GetTripleSlashTextSyntaxNode(),
179-
GetXmlAttributedElement(internalTextNodes, "typeparam", "name", typeParam.Name),
180-
GetNewLineTextSyntaxNode()
181-
];
182+
// TODO
183+
return GetFullTripleSlashXmlSyntaxNode(GetXmlAttributedElement(internalTextNodes, "typeparam", "name", typeParam.Name));
182184
}
183185

184186
private XmlNodeSyntax[] GetParamNodes()
@@ -188,7 +190,7 @@ private XmlNodeSyntax[] GetParamNodes()
188190
return [];
189191
}
190192

191-
SyntaxList<XmlNodeSyntax> paramNodes = SyntaxFactory.List<XmlNodeSyntax>();
193+
List<XmlNodeSyntax> paramNodes = new();
192194
foreach (DocsParam param in _api.Params)
193195
{
194196
paramNodes.AddRange(GetParamNode(param));
@@ -202,7 +204,7 @@ private XmlNodeSyntax[] GetParamNode(DocsParam param)
202204
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
203205
foreach (string line in param.Value.Split(_NewLineSeparators, _NewLineSplitOptions))
204206
{
205-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
207+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
206208
}
207209

208210
return [
@@ -219,15 +221,15 @@ private XmlNodeSyntax[] GetReturnsNodes()
219221
return [];
220222
}
221223

222-
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
224+
List<XmlNodeSyntax> internalTextNodes = new();
223225
foreach (string line in _api.Returns.Split(_NewLineSeparators, _NewLineSplitOptions))
224226
{
225-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
227+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
226228
}
227229

228230
return [
229231
GetTripleSlashTextSyntaxNode(),
230-
SyntaxFactory.XmlReturnsElement(internalTextNodes),
232+
SyntaxFactory.XmlReturnsElement(internalTextNodes.ToArray()),
231233
GetNewLineTextSyntaxNode(),
232234
];
233235
}
@@ -239,15 +241,15 @@ private XmlNodeSyntax[] GetRemarksNodes()
239241
return [];
240242
}
241243

242-
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
244+
List<XmlNodeSyntax> internalTextNodes = new();
243245
foreach (string line in _api.Remarks.Split(_NewLineSeparators, _NewLineSplitOptions))
244246
{
245-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
247+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
246248
}
247249

248250
return [
249251
GetTripleSlashTextSyntaxNode(),
250-
SyntaxFactory.XmlRemarksElement(internalTextNodes),
252+
SyntaxFactory.XmlRemarksElement(internalTextNodes.ToArray()),
251253
GetNewLineTextSyntaxNode(),
252254
];
253255
}
@@ -259,7 +261,7 @@ private XmlNodeSyntax[] GetExceptionNodes()
259261
return [];
260262
}
261263

262-
SyntaxList<XmlNodeSyntax> exceptionNodes = SyntaxFactory.List<XmlNodeSyntax>();
264+
List<XmlNodeSyntax> exceptionNodes = new();
263265
foreach (DocsException exception in _api.Exceptions)
264266
{
265267
exceptionNodes.AddRange(GetExceptionNode(exception));
@@ -273,7 +275,7 @@ private XmlNodeSyntax[] GetExceptionNode(DocsException exception)
273275
SyntaxList<XmlNodeSyntax> internalTextNodes = SyntaxFactory.List<XmlNodeSyntax>();
274276
foreach (string line in exception.Value.Split(_NewLineSeparators, _NewLineSplitOptions))
275277
{
276-
internalTextNodes.Add(GetTripleSlashSingleLineXmlTextSyntaxNode(_indentationTrivia, line));
278+
internalTextNodes.Add(GetFullTripleSlashSingleLineXmlTextSyntaxNode(line));
277279
}
278280

279281
return [
@@ -289,8 +291,6 @@ private XmlElementSyntax GetXmlAttributedElement(IEnumerable<XmlNodeSyntax> cont
289291
Debug.Assert(!string.IsNullOrWhiteSpace(attributeName));
290292
Debug.Assert(!string.IsNullOrWhiteSpace(attributeValue));
291293

292-
XmlElementStartTagSyntax startTag = SyntaxFactory.XmlElementStartTag(SyntaxFactory.XmlName(SyntaxFactory.Identifier(tagName)));
293-
294294
SyntaxToken xmlAttributeName = SyntaxFactory.Identifier(
295295
leading: SyntaxFactory.TriviaList(SyntaxFactory.Space),
296296
text: attributeName,
@@ -302,69 +302,96 @@ private XmlElementSyntax GetXmlAttributedElement(IEnumerable<XmlNodeSyntax> cont
302302
identifier: SyntaxFactory.IdentifierName(attributeValue),
303303
endQuoteToken: SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken));
304304

305-
SyntaxList<XmlAttributeSyntax> startTagAttributes = SyntaxFactory.SingletonList<XmlAttributeSyntax>(xmlAttribute);
306-
307-
startTag = startTag.WithAttributes(startTagAttributes);
305+
XmlElementStartTagSyntax startTag = SyntaxFactory
306+
.XmlElementStartTag(SyntaxFactory.XmlName(SyntaxFactory.Identifier(tagName)))
307+
.WithAttributes(SyntaxFactory.List<XmlAttributeSyntax>([xmlAttribute]));
308308

309309
XmlElementEndTagSyntax endTag = SyntaxFactory.XmlElementEndTag(SyntaxFactory.XmlName(SyntaxFactory.Identifier(tagName)));
310310

311311
return SyntaxFactory.XmlElement(startTag, SyntaxFactory.List(content), endTag);
312312
}
313313

314+
private XmlNodeSyntax[] GetFullTripleSlashXmlSyntaxNode(XmlNodeSyntax existingNode)
315+
{
316+
GetIndentationSyntaxToken(out SyntaxToken indentationSyntaxToken);
317+
GetTripleSlashSyntaxToken(out SyntaxToken tripleSlashSyntaxToken);
318+
GetNewLineSyntaxToken(out SyntaxToken newLineSyntaxToken);
319+
320+
return [
321+
SyntaxFactory.XmlText(new SyntaxToken[] { indentationSyntaxToken, tripleSlashSyntaxToken }),
322+
existingNode,
323+
SyntaxFactory.XmlText(SyntaxFactory.TokenList(newLineSyntaxToken)),
324+
];
325+
}
326+
314327
// Returns a single line of triple slash comments plus the optional line of text that may follow it.
315328
// [indentation][tripleslash][textline][newline]
316329
// Example: ->->->/// text\n
317-
private XmlTextSyntax GetTripleSlashSingleLineXmlTextSyntaxNode(SyntaxTrivia? indentationTrivia, string? text = null)
330+
private XmlTextSyntax GetFullTripleSlashSingleLineXmlTextSyntaxNode(string text)
318331
{
319-
SyntaxTokenList syntaxTokenList = SyntaxFactory.TokenList();
320-
321-
syntaxTokenList.Add(GetIndentationSyntaxToken(indentationTrivia));
322-
syntaxTokenList.Add(GetTripleSlashSyntaxToken());
323-
if (text != null)
324-
{
325-
syntaxTokenList.Add(SyntaxFactory.XmlTextNewLine(
332+
GetIndentationSyntaxToken(out SyntaxToken indentationSyntaxToken);
333+
GetTripleSlashSyntaxToken(out SyntaxToken tripleSlashSyntaxToken);
334+
GetNewLineSyntaxToken(out SyntaxToken newLineSyntaxToken);
335+
336+
SyntaxToken[] syntaxTokenList = [
337+
indentationSyntaxToken,
338+
tripleSlashSyntaxToken,
339+
SyntaxFactory.XmlTextNewLine(
326340
leading: SyntaxFactory.TriviaList(),
327341
text: text,
328342
value: text,
329-
trailing: SyntaxFactory.TriviaList()));
330-
}
331-
syntaxTokenList.Add(GetNewLineSyntaxToken());
343+
trailing: SyntaxFactory.TriviaList()),
344+
newLineSyntaxToken
345+
];
332346

333-
return SyntaxFactory.XmlText().WithTextTokens(syntaxTokenList);
347+
return SyntaxFactory.XmlText(SyntaxFactory.TokenList(syntaxTokenList));
334348
}
335349

336350
// Returns a syntax node containing the "/// " text literal syntax token.
337-
private XmlTextSyntax GetTripleSlashTextSyntaxNode() =>
338-
SyntaxFactory.XmlText().WithTextTokens(SyntaxFactory.TokenList(GetTripleSlashSyntaxToken()));
351+
private XmlTextSyntax GetTripleSlashTextSyntaxNode()
352+
{
353+
GetTripleSlashSyntaxToken(out SyntaxToken tripleSlashSyntaxToken);
354+
return SyntaxFactory.XmlText().WithTextTokens(SyntaxFactory.TokenList(tripleSlashSyntaxToken));
355+
}
339356

340357
// Returns a syntax node containing the "\n" text literal syntax token.
341-
private XmlTextSyntax GetNewLineTextSyntaxNode() =>
342-
SyntaxFactory.XmlText().WithTextTokens(SyntaxFactory.TokenList(GetNewLineSyntaxToken()));
358+
private XmlTextSyntax GetNewLineTextSyntaxNode()
359+
{
360+
GetNewLineSyntaxToken(out SyntaxToken newLineSyntaxToken);
361+
return SyntaxFactory.XmlText().WithTextTokens(SyntaxFactory.TokenList(newLineSyntaxToken));
362+
}
343363

344-
// Returns a syntax token with the "" text literal preceded by the specified indentation trivia.
345-
private SyntaxToken GetIndentationSyntaxToken(SyntaxTrivia? indentationTrivia) =>
346-
SyntaxFactory.XmlTextLiteral(
347-
leading: indentationTrivia != null ? SyntaxFactory.TriviaList(indentationTrivia.Value) : SyntaxFactory.TriviaList(),
348-
text: string.Empty,
349-
value: string.Empty,
350-
trailing: SyntaxFactory.TriviaList());
364+
// Returns a syntax node containing the specified indentation text literal syntax token.
365+
private XmlTextSyntax GetIndentationTextSyntaxNode()
366+
{
367+
GetIndentationSyntaxToken(out SyntaxToken indentationSyntaxToken);
368+
return SyntaxFactory.XmlText().WithTextTokens(SyntaxFactory.TokenList(indentationSyntaxToken));
369+
}
351370

352371
// Returns a syntax token containing the "/// " text literal.
353-
private SyntaxToken GetTripleSlashSyntaxToken() =>
354-
SyntaxFactory.XmlTextLiteral(
372+
private void GetTripleSlashSyntaxToken(out SyntaxToken tripleSlashSyntaxToken) =>
373+
tripleSlashSyntaxToken = SyntaxFactory.XmlTextLiteral(
355374
leading: SyntaxFactory.TriviaList(SyntaxFactory.DocumentationCommentExterior(TripleSlash)),
356375
text: Space,
357376
value: Space,
358377
trailing: SyntaxFactory.TriviaList());
359378

360379
// Returns a syntax token containing the "\n" text literal.
361-
private SyntaxToken GetNewLineSyntaxToken() =>
362-
SyntaxFactory.XmlTextNewLine(
380+
private void GetNewLineSyntaxToken(out SyntaxToken newLineSyntaxToken) =>
381+
newLineSyntaxToken = SyntaxFactory.XmlTextNewLine(
363382
leading: SyntaxFactory.TriviaList(),
364383
text: NewLine,
365384
value: NewLine,
366385
trailing: SyntaxFactory.TriviaList());
367386

387+
// Returns a syntax token with the "" text literal preceded by the specified indentation trivia.
388+
private void GetIndentationSyntaxToken(out SyntaxToken indentationSyntaxToken) =>
389+
indentationSyntaxToken = SyntaxFactory.XmlTextLiteral(
390+
leading: SyntaxFactory.TriviaList(_indentationTrivia),
391+
text: string.Empty,
392+
value: string.Empty,
393+
trailing: SyntaxFactory.TriviaList());
394+
368395
private static bool DoesNodeHaveTag(SyntaxNode xmlNode, string tagName, string? attributeName = null, string? attributeValue = null)
369396
{
370397
if (xmlNode.Kind() is SyntaxKind.XmlElement && xmlNode is XmlElementSyntax xmlElement)

0 commit comments

Comments
 (0)
0