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

Commit db1270b

Browse files
carlossanlopcarlossanlop
committed
merge conflict fix
2 parents 22e4830 + d986783 commit db1270b

File tree

74 files changed

+1152
-644
lines changed

Some content is hidden

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

74 files changed

+1152
-644
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ bin
55
obj
66
.ionide/
77
artifacts/
8+
*/*.user

‎Libraries/Configuration.cs

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ private enum Mode
4343
PortTypeRemarks,
4444
PortTypeSummaries,
4545
PortTypeTypeParams, // TypeParams of a Type
46+
PrintSummaryDetails,
4647
PrintUndoc,
4748
Save,
4849
SkipInterfaceImplementations,
@@ -53,15 +54,31 @@ private enum Mode
5354
// considers an empty (undocumented) API element.
5455
public static readonly string ToBeAdded = "To be added.";
5556

56-
public static readonly string[] ForbiddenBinSubdirectories = new[] { "binplacePackages", "docs", "mscorlib", "native", "netfx", "netstandard", "pkg", "Product", "ref", "runtime", "shimsTargetRuntime", "testhost", "tests", "winrt" };
57+
public static readonly string[] ForbiddenBinSubdirectories = new[] {
58+
"binplacePackages",
59+
"docs",
60+
"externals",
61+
"mscorlib",
62+
"native",
63+
"netfx",
64+
"netstandard",
65+
"pkg",
66+
"Product",
67+
"ref",
68+
"runtime",
69+
"shimsTargetRuntime",
70+
"testhost",
71+
"tests",
72+
"winrt"
73+
};
5774

5875
public readonly string BinLogPath = "output.binlog";
5976
public bool BinLogger { get; private set; } = false;
6077
public FileInfo? CsProj { get; set; }
6178
public PortingDirection Direction { get; set; } = PortingDirection.ToDocs;
6279
public List<DirectoryInfo> DirsIntelliSense { get; } = new List<DirectoryInfo>();
6380
public List<DirectoryInfo> DirsDocsXml { get; } = new List<DirectoryInfo>();
64-
public bool DisablePrompts { get; set; } = false;
81+
public bool DisablePrompts { get; set; } = true;
6582
public int ExceptionCollisionThreshold { get; set; } = 70;
6683
public HashSet<string> ExcludedAssemblies { get; } = new HashSet<string>();
6784
public HashSet<string> ExcludedNamespaces { get; } = new HashSet<string>();
@@ -87,6 +104,7 @@ private enum Mode
87104
/// TypeParams of a Type.
88105
/// </summary>
89106
public bool PortTypeTypeParams { get; set; } = true;
107+
public bool PrintSummaryDetails { get; set; } = false;
90108
public bool PrintUndoc { get; set; } = false;
91109
public bool Save { get; set; } = false;
92110
public bool SkipInterfaceImplementations { get; set; } = false;
@@ -100,7 +118,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
100118

101119
if (args == null || args.Length == 0)
102120
{
103-
Log.PrintHelpAndError("No arguments passed to the executable.");
121+
Log.ErrorAndExit("No arguments passed to the executable.");
104122
}
105123

106124
Configuration config = new Configuration();
@@ -219,7 +237,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
219237
}
220238
else
221239
{
222-
Log.PrintHelpAndError("You must specify at least one assembly.");
240+
Log.ErrorAndExit("You must specify at least one assembly.");
223241
}
224242

225243
mode = Mode.Initial;
@@ -241,7 +259,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
241259
}
242260
else
243261
{
244-
Log.PrintHelpAndError("You must specify at least one namespace.");
262+
Log.ErrorAndExit("You must specify at least one namespace.");
245263
}
246264

247265
mode = Mode.Initial;
@@ -263,7 +281,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
263281
}
264282
else
265283
{
266-
Log.PrintHelpAndError("You must specify at least one type name.");
284+
Log.ErrorAndExit("You must specify at least one type name.");
267285
}
268286

269287
mode = Mode.Initial;
@@ -285,7 +303,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
285303
}
286304
else
287305
{
288-
Log.PrintHelpAndError("You must specify at least one assembly.");
306+
Log.ErrorAndExit("You must specify at least one assembly.");
289307
}
290308

291309
mode = Mode.Initial;
@@ -307,7 +325,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
307325
}
308326
else
309327
{
310-
Log.PrintHelpAndError("You must specify at least one namespace.");
328+
Log.ErrorAndExit("You must specify at least one namespace.");
311329
}
312330

313331
mode = Mode.Initial;
@@ -329,7 +347,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
329347
}
330348
else
331349
{
332-
Log.PrintHelpAndError("You must specify at least one type name.");
350+
Log.ErrorAndExit("You must specify at least one type name.");
333351
}
334352

335353
mode = Mode.Initial;
@@ -446,6 +464,10 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
446464
mode = Mode.PortTypeTypeParams;
447465
break;
448466

467+
case "-PRINTSUMMARYDETAILS":
468+
mode = Mode.PrintSummaryDetails;
469+
break;
470+
449471
case "-PRINTUNDOC":
450472
mode = Mode.PrintUndoc;
451473
break;
@@ -463,7 +485,7 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
463485
break;
464486

465487
default:
466-
Log.PrintHelpAndError($"Unrecognized argument: {arg}");
488+
Log.ErrorAndExit($"Unrecognized argument: {arg}");
467489
break;
468490
}
469491
break;
@@ -574,6 +596,13 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
574596
break;
575597
}
576598

599+
case Mode.PrintSummaryDetails:
600+
{
601+
config.PrintSummaryDetails = ParseOrExit(arg, "Print summary details");
602+
mode = Mode.Initial;
603+
break;
604+
}
605+
577606
case Mode.PrintUndoc:
578607
{
579608
config.PrintUndoc = ParseOrExit(arg, "Print undoc");
@@ -604,41 +633,41 @@ public static Configuration GetCLIArgumentsForDocsPortingTool(string[] args)
604633

605634
default:
606635
{
607-
Log.PrintHelpAndError("Unexpected mode.");
636+
Log.ErrorAndExit("Unexpected mode.");
608637
break;
609638
}
610639
}
611640
}
612641

613642
if (mode != Mode.Initial)
614643
{
615-
Log.PrintHelpAndError("You missed an argument value.");
644+
Log.ErrorAndExit("You missed an argument value.");
616645
}
617646

618647
if (config.DirsDocsXml == null)
619648
{
620-
Log.PrintHelpAndError($"You must specify a path to the dotnet-api-docs xml folder using '-{nameof(Mode.Docs)}'.");
649+
Log.ErrorAndExit($"You must specify a path to the dotnet-api-docs xml folder using '-{nameof(Mode.Docs)}'.");
621650
}
622651

623652
if (config.Direction == PortingDirection.ToDocs)
624653
{
625654
if (config.DirsIntelliSense.Count == 0)
626655
{
627-
Log.PrintHelpAndError($"You must specify at least one IntelliSense & DLL folder using '-{nameof(Mode.IntelliSense)}'.");
656+
Log.ErrorAndExit($"You must specify at least one IntelliSense & DLL folder using '-{nameof(Mode.IntelliSense)}'.");
628657
}
629658
}
630659

631660
if (config.Direction == PortingDirection.ToTripleSlash)
632661
{
633662
if (config.CsProj == null)
634663
{
635-
Log.PrintHelpAndError($"You must specify a *.csproj file using '-{nameof(Mode.CsProj)}'.");
664+
Log.ErrorAndExit($"You must specify a *.csproj file using '-{nameof(Mode.CsProj)}'.");
636665
}
637666
}
638667

639668
if (config.IncludedAssemblies.Count == 0)
640669
{
641-
Log.PrintHelpAndError($"You must specify at least one assembly with {nameof(IncludedAssemblies)}.");
670+
Log.ErrorAndExit($"You must specify at least one assembly with {nameof(IncludedAssemblies)}.");
642671
}
643672

644673
return config;

‎Libraries/Docs/DocsAPI.cs

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ namespace Libraries.Docs
88
{
99
public abstract class DocsAPI : IDocsAPI
1010
{
11-
private string? _docIdEscaped = null;
1211
private DocsSummary? _summary;
1312
private DocsRemarks? _remarks;
1413
private List<DocsExample>? _examples;
@@ -25,6 +24,12 @@ public abstract class DocsAPI : IDocsAPI
2524

2625
protected DocsAPI(XElement xeRoot) => XERoot = xeRoot;
2726

27+
public bool IsUndocumented =>
28+
Summary.IsDocsEmpty() ||
29+
Returns.IsDocsEmpty() ||
30+
Params.Any(p => p.Value.IsDocsEmpty()) ||
31+
TypeParams.Any(tp => tp.Value.IsDocsEmpty());
32+
2833
public abstract bool Changed { get; set; }
2934
public string FilePath { get; set; } = string.Empty;
3035
public abstract string DocId { get; }
@@ -135,7 +140,7 @@ public List<string> SeeAlsoCrefs
135140
{
136141
if (Docs != null)
137142
{
138-
_seeAlsoCrefs = Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref")).ToList();
143+
_seeAlsoCrefs = Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList();
139144
}
140145
else
141146
{
@@ -154,7 +159,7 @@ public List<string> AltMembers
154159
{
155160
if (Docs != null)
156161
{
157-
_altMemberCrefs = Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref")).ToList();
162+
_altMemberCrefs = Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList();
158163
}
159164
else
160165
{
@@ -185,6 +190,8 @@ public List<DocsRelated> Relateds
185190
}
186191

187192
public abstract string Summary { get; set; }
193+
public abstract string ReturnType { get; }
194+
public abstract string Returns { get; set; }
188195

189196
public DocsSummary SummaryElement
190197
{
@@ -263,18 +270,6 @@ public List<DocsAssemblyInfo> AssemblyInfos
263270
}
264271
}
265272

266-
public string DocIdEscaped
267-
{
268-
get
269-
{
270-
if (_docIdEscaped == null)
271-
{
272-
_docIdEscaped = DocId.Replace("<", "{").Replace(">", "}").Replace("&lt;", "{").Replace("&gt;", "}");
273-
}
274-
return _docIdEscaped;
275-
}
276-
}
277-
278273
public DocsParam SaveParam(XElement xeIntelliSenseXmlParam)
279274
{
280275
XElement xeDocsParam = new(xeIntelliSenseXmlParam.Name);

‎Libraries/Docs/DocsCommentsContainer.cs

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ public class DocsCommentsContainer
1414

1515
private XDocument? xDoc = null;
1616

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

2020
public DocsCommentsContainer(Configuration config)
2121
{
@@ -47,26 +47,19 @@ public void Save()
4747
return;
4848
}
4949

50-
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
51-
Encoding encoding = Encoding.GetEncoding(1252); // Preserves original xml encoding from Docs repo
52-
53-
List<string> savedFiles = new List<string>();
54-
foreach (var type in Types.Where(x => x.Changed))
50+
List<string> savedFiles = new();
51+
foreach (var type in Types.Values.Where(x => x.Changed))
5552
{
56-
Log.Warning(false, $"Saving changes for {type.FilePath}:");
53+
Log.Info(false, $"Saving changes for {type.FilePath} ... ");
5754

5855
try
5956
{
60-
StreamReader sr = new StreamReader(type.FilePath);
61-
int x = sr.Read(); // Force the first read to be done so the encoding is detected
62-
sr.Close();
63-
6457
// These settings prevent the addition of the <xml> element on the first line and will preserve indentation+endlines
65-
XmlWriterSettings xws = new XmlWriterSettings
58+
XmlWriterSettings xws = new()
6659
{
60+
Encoding = type.FileEncoding,
6761
OmitXmlDeclaration = true,
6862
Indent = true,
69-
Encoding = encoding,
7063
CheckCharacters = false
7164
};
7265

@@ -79,15 +72,14 @@ public void Save()
7972
string fileData = File.ReadAllText(type.FilePath);
8073
if (!fileData.EndsWith(Environment.NewLine))
8174
{
82-
File.WriteAllText(type.FilePath, fileData + Environment.NewLine, encoding);
75+
File.WriteAllText(type.FilePath, fileData + Environment.NewLine, type.FileEncoding);
8376
}
8477

8578
Log.Success(" [Saved]");
8679
}
8780
catch (Exception e)
8881
{
89-
Log.Error(e.Message);
90-
Log.Line();
82+
Log.Error("Failed to write to {0}. {1}", type.FilePath, e.Message);
9183
Log.Error(e.StackTrace ?? string.Empty);
9284
if (e.InnerException != null)
9385
{
@@ -96,10 +88,7 @@ public void Save()
9688
Log.Line();
9789
Log.Error(e.InnerException.StackTrace ?? string.Empty);
9890
}
99-
System.Threading.Thread.Sleep(1000);
10091
}
101-
102-
Log.Line();
10392
}
10493
}
10594

@@ -174,19 +163,30 @@ pr 10000 ivate IEnumerable<FileInfo> EnumerateFiles()
174163

175164
private void LoadFile(FileInfo fileInfo)
176165
{
177-
if (!fileInfo.Exists)
166+
Encoding? encoding = null;
167+
try
178168
{
179-
throw new Exception($"Docs xml file does not exist: {fileInfo.FullName}");
180-
}
169+
var utf8NoBom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
170+
var utf8Bom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: true);
171+
using (StreamReader sr = new(fileInfo.FullName, utf8NoBom, detectEncodingFromByteOrderMarks: true))
172+
{
173+
xDoc = XDocument.Load(sr);
174+
encoding = sr.CurrentEncoding;
175+
}
181176

182-
xDoc = XDocument.Load(fileInfo.FullName);
177+
}
178+
catch(Exception ex)
179+
{
180+
Log.Error($"Failed to load '{fileInfo.FullName}'. {ex}");
181+
return;
182+
}
183183

184184
if (IsXmlMalformed(xDoc, fileInfo.FullName))
185185
{
186186
return;
187187
}
188188

189-
DocsType docsType = new DocsType(fileInfo.FullName, xDoc, xDoc.Root!);
189+
DocsType docsType = new DocsType(fileInfo.FullName, xDoc, xDoc.Root!, encoding);
190190

191191
bool add = false;
192192
bool addedAsInterface = false;
@@ -237,15 +237,15 @@ private void LoadFile(FileInfo fileInfo)
237237
if (add)
238238
{
239239
int totalMembersAdded = 0;
240-
Types.Add(docsType);
240+
Types.TryAdd(docsType.DocId, docsType); // is it OK this encounters duplicates?
241241

242242
if (XmlHelper.TryGetChildElement(xDoc.Root!, "Members", out XElement? xeMembers) && xeMembers != null)
243243
{
244244
foreach (XElement xeMember in xeMembers.Elements("Member"))
245245
{
246246
DocsMember member = new DocsMember(fileInfo.FullName, docsType, xeMember);
247247
totalMembersAdded++;
248-
Members.Add(member);
248+
Members.TryAdd(member.DocId, member); // is it OK this encounters duplicates?
249249
}
250250
}
251251

0 commit comments

Comments
 (0)
0