8000 merge conflict fix · dotnet/api-docs-sync@c285525 · GitHub
[go: up one dir, main page]
Skip to content

Commit c285525

Browse files
carlossanlopcarlossanlop
committed
merge conflict fix
1 parent d986783 commit c285525

Some content is hidden

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

60 files changed

+3675
-756
lines changed

‎Libraries/Docs/APIKind.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
namespace Libraries.Docs
22
{
3-
internal enum APIKind
3+
public enum APIKind
44
{
55
Type,
66
Member

‎Libraries/Docs/DocsAPI.cs

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@
66

77
namespace Libraries.Docs
88
{
9-
internal abstract class DocsAPI : IDocsAPI
9+
public abstract class DocsApi : IDocsAPI
1010
{
11+
private DocsSummary? _summary;
12+
private DocsRemarks? _remarks;
13+
private List<DocsExample>? _examples;
1114
private List<DocsParam>? _params;
1215
private List<DocsParameter>? _parameters;
1316
private List<DocsTypeParameter>? _typeParameters;
@@ -19,7 +22,7 @@ internal abstract class DocsAPI : IDocsAPI
1922

2023
protected readonly XElement XERoot;
2124

22-
protected DocsAPI(XElement xeRoot) => XERoot = xeRoot;
25+
protected DocsApi(XElement xeRoot) => XERoot = xeRoot;
2326

2427
public bool IsUndocumented =>
2528
Summary.IsDocsEmpty() ||
@@ -190,8 +193,71 @@ public List<DocsRelated> Relateds
190193
public abstract string ReturnType { get; }
191194
public abstract string Returns { get; set; }
192195

196+
public DocsSummary SummaryElement
197+
{
198+
get
199+
{
200+
if (_summary == null)
201+
{
202+
XElement? xe = Docs?.Element("summary");
203+
204+
if (xe != null)
205+
{
206+
_summary = new(xe);
207+
}
208+
else
209+
{
210+
throw new InvalidOperationException($"There was no <summary> element. Doc ID: {DocId}");
211+
}
212+
}
213+
214+
return _summary;
215+
}
216+
}
217+
193218
public abstract string Remarks { get; set; }
194219

220+
public DocsRemarks RemarksElement
221+
{
222+
get
223+
{
224+
if (_remarks == null)
225+
{
226+
XElement? xe = Docs?.Element("remarks");
227+
228+
if (xe != null)
229+
{
230+
_remarks = new(xe);
231+
232+
if (!_remarks.ExampleContent?.ParsedText?.IsDocsEmpty() ?? false)
233+
{
234+
ExampleElements.Add(_remarks.ExampleContent!);
235+
}
236+
}
237+
else
238+
{
239+
_remarks = new(new XElement("remarks"));
240+
}
241+
}
242+
243+
return _remarks;
244+
}
245+
}
246+
247+
public List<DocsExample> ExampleElements
248+
{
249+
get
250+
{
251+
if (_examples == null)
252+
{
253+
IEnumerable<XElement> elems = Docs.Elements("example");
254+
_examples = elems.Select(e => new DocsExample(e)).ToList();
255+
}
256+
257+
return _examples;
258+
}
259+
}
260+
195261
public List<DocsAssemblyInfo> AssemblyInfos
196262
{
197263
get
@@ -206,10 +272,10 @@ public List<DocsAssemblyInfo> AssemblyInfos
206272

207273
public DocsParam SaveParam(XElement xeIntelliSenseXmlParam)
208274
{
209-
XElement xeDocsParam = new XElement(xeIntelliSenseXmlParam.Name);
275+
XElement xeDocsParam = new(xeIntelliSenseXmlParam.Name);
210276
xeDocsParam.ReplaceAttributes(xeIntelliSenseXmlParam.Attributes());
211277
XmlHelper.SaveFormattedAsXml(xeDocsParam, xeIntelliSenseXmlParam.Value);
212-
DocsParam docsParam = new DocsParam(this, xeDocsParam);
278+
DocsParam docsParam = new(this, xeDocsParam);
213279
Changed = true;
214280
return docsParam;
215281
}
@@ -229,7 +295,7 @@ public APIKind Kind
229295

230296
public DocsTypeParam AddTypeParam(string name, string value)
231297
{
232-
XElement typeParam = new XElement("typeparam");
298+
XElement typeParam = new("typeparam");
233299
typeParam.SetAttributeValue("name", name);
234300
XmlHelper.AddChildFormattedAsXml(Docs, typeParam, value);
235301
Changed = true;

‎Libraries/Docs/DocsApiReference.cs

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
using System.Collections.Generic;
2+
using System.Diagnostics;
3+
using System.Linq;
4+
using System.Text.RegularExpressions;
5+
using static System.Net.WebUtility;
6+
7+
namespace Libraries.Docs
8+
{
9+
public class DocsApiReference
10+
{
11+
public bool IsOverload { get; private init; }
12+
13+
public char? Prefix { get; private init; }
14+
15+
public string Api { get; private init; }
16+
17+
// Generic parameters need to support both single and double backtick conventions
18+
private const string GenericParameterPattern = @"`{1,2}(?<arity>\d+)";
19+
private const string ApiChars = @"[A-Za-z0-9\-\._~:\/#\[\]\{\}@!\$&'\(\)\*\+,;`]";
20+
private const string ApiReferencePattern = @"((?<prefix>[A-Za-z]):)?(?<api>(" + ApiChars + @")+)?(?<extraVars>\?(" + ApiChars + @")+=(" + ApiChars + @")+)?";
21+
private static readonly Regex XrefPattern = new("<xref:(?<api>" + ApiReferencePattern + ")\\s*>", RegexOptions.Compiled);
22+
23+
public DocsApiReference(string apiReference)
24+
{
25+
Api = UrlDecode(apiReference);
26+
var match = Regex.Match(Api, ApiReferencePattern);
27+
28+
if (match.Success)
29+
{
30+
Api = match.Groups["api"].Value;
31+
32+
if (match.Groups["prefix"].Success)
33+
{
34+
Prefix = match.Groups["prefix"].Value[0];
35+
IsOverload = Prefix == 'O';
36+
}
37+
}
38+
39+
if (Api.EndsWith('*'))
40+
{
41+
IsOverload = true;
42+
Api = Api[..^1];
43+
}
44+
45+
Api = ReplacePrimitivesWithShorthands(Api);
46+
Api = ParseGenericTypes(Api);
47+
}
48+
49+
public override string ToString()
50+
{
51+
if (Prefix is not null)
52+
{
53+
return $"{Prefix}:{Api}";
54+
}
55+
56+
return Api;
57+
}
58+
59+
private static readonly Dictionary<string, string> PrimitiveTypes = new()
60+
{
61+
{ "System.Boolean", "bool" },
62+
{ "System.Byte", "byte" },
63+
{ "System.Char", "char" },
64+
{ "System.Decimal", "decimal" },
65+
{ "System.Double", "double" },
66+
{ "System.Int16", "short" },
67+
{ "System.Int32", "int" },
68+
{ "System.Int64", "long" },
69+
{ "System.Object", "object" }, // Ambiguous: could be 'object' or 'dynamic' https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/built-in-types
70+
{ "System.SByte", "sbyte" },
71+
{ "System.Single", "float" },
72+
{ "System.String", "string" },
73+
{ "System.UInt16", "ushort" },
74+
{ "System.UInt32", "uint" },
75+
{ "System.UInt64", "ulong" },
76+
{ "System.Void", "void" }
77+
};
78+
79+
public static string ReplacePrimitivesWithShorthands(string apiReference)
80+
{
81+
foreach ((string key, string value) in PrimitiveTypes)
82+
{
83+
apiReference = Regex.Replace(apiReference, key, value);
84+
}
85+
86+
return apiReference;
87+
}
88+
89+
public static string ParseGenericTypes(string apiReference)
90+
{
91+
int genericParameterArity = 0;
92+
return Regex.Replace(apiReference, GenericParameterPattern, MapGenericParameter);
93+
94+
string MapGenericParameter(Match match)
95+
{
96+
int arity = int.Parse(match.Groups["arity"].Value);
97+
98+
if (genericParameterArity == 0)
99+
{
100+
// This is the first match that declares the generic parameter arity of the method
101+
// e.g. GenericMethod``3 ---> GenericMethod{T1,T2,T3}(...);
102+
Debug.Assert(arity > 0);
103+
genericParameterArity = arity;
104+
return WrapInCurlyBrackets(string.Join(",", Enumerable.Range(0, arity).Select(CreateGenericParameterName)));
105+
}
106+
107+
// Subsequent matches are references to generic parameters in the method signature,
108+
// e.g. GenericMethod{T1,T2,T3}(..., List{``1} parameter, ...); ---> List{T2} parameter
109+
return CreateGenericParameterName(arity);
110+
111+
// This naming scheme does not map to the exact generic parameter names;
112+
// however this is still accepted by intellisense and backporters can rename
113+
// manually with the help of tooling.
114+
string CreateGenericParameterName(int index) => genericParameterArity == 1 ? "T" : $"T{index + 1}";
115+
116+
static string WrapInCurlyBrackets(string input) => $"{{{input}}}";
117+
}
118+
}
119+
120+
public static string ReplaceMarkdownXrefWithSeeCref(string markdown)
121+
{
122+
return XrefPattern.Replace(markdown, match =>
123+
{
124+
var api = new DocsApiReference(match.Groups["api"].Value);
125+
return @$"<see cref=""{api}"" />";
126+
});
127+
}
128+
}
129+
}

‎Libraries/Docs/DocsAssemblyInfo.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
namespace Libraries.Docs
66
{
7-
internal class DocsAssemblyInfo
7+
public class DocsAssemblyInfo
88
{
99
private readonly XElement XEAssemblyInfo;
1010
public string AssemblyName

‎Libraries/Docs/DocsAttribute.cs

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
using System.Xml.Linq;
1+
using System.Linq;
2+
using System.Xml.Linq;
23

34
namespace Libraries.Docs
45
{
5-
internal class DocsAttribute
6+
public class DocsAttribute
67
{
78
private readonly XElement XEAttribute;
89

@@ -13,12 +14,15 @@ public string FrameworkAlternate
1314
return XmlHelper.GetAttributeValue(XEAttribute, "FrameworkAlternate");
1415
}
1516
}
16-
public string AttributeName
17+
18+
public string? AttributeName
1719
{
18-
get
19-
{
20-
return XmlHelper.GetChildElementValue(XEAttribute, "AttributeName");
21-
}
20+
get => GetAttributeName("C#");
21+
}
22+
23+
public string? GetAttributeName(string language)
24+
{
25+
return XEAttribute.Elements("AttributeName").Where(x => XmlHelper.GetAttributeValue(x, "Language") == language).SingleOrDefault()?.Value;
2226
}
2327

2428
public DocsAttribute(XElement xeAttribute)

‎Libraries/Docs/DocsCommentsContainer.cs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88

99
namespace Libraries.Docs
1010
{
11-
internal class DocsCommentsContainer
11+
public class DocsCommentsContainer
1212
{
1313
private Configuration Config { get; set; }
1414

1515
private XDocument? xDoc = null;
1616

17-
public readonly Dictionary<string, DocsType> Types = new();
18-
public readonly Dictionary<string, DocsMember> Members = new();
17+
internal readonly Dictionary<string, DocsType> Types = new();
18+
internal readonly Dictionary<string, DocsMember> Members = new();
1919

2020
public DocsCommentsContainer(Configuration config)
2121
{

‎Libraries/Docs/DocsExample.cs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
using System.Diagnostics.CodeAnalysis;
2+
using System.Text.RegularExpressions;
3+
using System.Xml.Linq;
4+
5+
namespace Libraries.Docs
6+
{
7+
public class DocsExample : DocsMarkdownElement
8+
{
9+
public DocsExample(XElement xeExample) : base(xeExample)
10+
{
11+
}
12+
13+
protected override string ExtractElements(string markdown)
14+
{
15+
markdown = base.ExtractElements(markdown);
16+
markdown = RemoveMarkdownHeading(markdown, "Examples?");
17+
18+
return markdown;
19+
}
20+
}
21+
}

‎Libraries/Docs/DocsException.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
namespace Libraries.Docs
77
{
8-
internal class DocsException
8+
public class DocsException
99
{
1010
private readonly XElement XEException;
1111

0 commit comments

Comments
 (0)
0