8000 PortToDocs: Add methods that either collect files automatically, or a… · dotnet/api-docs-sync@149a093 · GitHub
[go: up one dir, main page]
Skip to content

Commit 149a093

Browse files
carlossanlopcarlossanlop
authored
PortToDocs: Add methods that either collect files automatically, or allow passing documents manually (#110)
* PortToDocs: Add public method to collect files automatically, include method to allow collecting a file manually. * Apply some minor Roslyn suggestions. * Rename method in tests that ports from file to file.
1 parent 77ab3a9 commit 149a093

File tree

5 files changed

+107
-116
lines changed

5 files changed

+107
-116
lines changed

‎src/PortToDocs/src/app/PortToDocs.cs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ public static void Main(string[] args)
1111
{
1212
Configuration config = Configuration.GetCLIArguments(args);
1313
ToDocsPorter porter = new(config);
14+
porter.CollectFiles();
1415
porter.Start();
1516
}
1617
}

‎src/PortToDocs/src/libraries/Docs/DocsCommentsContainer.cs

Lines changed: 19 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -15,28 +15,10 @@ internal class DocsCommentsContainer
1515
{
1616
private Configuration Config { get; set; }
1717

18-
private XDocument? xDoc = null;
19-
2018
public readonly Dictionary<string, DocsType> Types = new();
2119
public readonly Dictionary<string, DocsMember> Members = new();
2220

23-
public DocsCommentsContainer(Configuration config)
24-
{
25-
Config = config;
26-
}
27-
28-
public void CollectFiles()
29-
{
30-
Log.Info("Looking for Docs xml files...");
31-
32-
foreach (FileInfo fileInfo in EnumerateFiles())
33-
{
34-
LoadFile(fileInfo);
35-
}
36-
37-
Log.Success("Finished looking for Docs xml files.");
38-
Log.Line();
39-
}
21+
public DocsCommentsContainer(Configuration config) => Config = config;
4022

4123
public void Save()
4224
{
@@ -51,7 +33,7 @@ public void Save()
5133
}
5234

5335
List<string> savedFiles = new();
54-
foreach (var type in Types.Values.Where(x => x.Changed))
36+
foreach (DocsType type in Types.Values.Where(x => x.Changed))
5537
{
5638
Log.Info(false, $"Saving changes for {type.FilePath} ... ");
5739

@@ -95,23 +77,11 @@ public void Save()
9577
}
9678
}
9779

98-
private bool HasAllowedDirName(DirectoryInfo dirInfo)
99-
{
100-
return !Configuration.ForbiddenBinSubdirectories.Contains(dirInfo.Name) && !dirInfo.Name.EndsWith(".Tests");
101-
}
102-
103-
private bool HasAllowedFileName(FileInfo fileInfo)
104-
{
105-
return !fileInfo.Name.StartsWith("ns-") &&
106-
fileInfo.Name != "index.xml" &&
107-
fileInfo.Name != "_filter.xml";
108-
}
109-
110-
private IEnumerable<FileInfo> EnumerateFiles()
80+
internal IEnumerable<FileInfo> EnumerateFiles()
11181
{
11282
// Union avoids duplication
113-
var includedAssembliesAndNamespaces = Config.IncludedAssemblies.Union(Config.IncludedNamespaces);
114-
var excludedAssembliesAndNamespaces = Config.ExcludedAssemblies.Union(Config.ExcludedNamespaces);
83+
IEnumerable<string> includedAssembliesAndNamespaces = Config.IncludedAssemblies.Union(Config.IncludedNamespaces);
84+
IEnumerable<string> excludedAssembliesAndNamespaces = Config.ExcludedAssemblies.Union(Config.ExcludedNamespaces);
11585

11686
foreach (DirectoryInfo rootDir in Config.DirsDocsXml)
11787
{
@@ -164,32 +134,14 @@ private IEnumerable<FileInfo> EnumerateFiles()
164134
}
165135
}
166136

167-
private void LoadFile(FileInfo fileInfo)
137+
internal void LoadDocsFile(XDocument xDoc, string filePath, Encoding encoding)
168138
{
169-
Encoding? encoding = null;
170-
try
171-
{
172-
var utf8NoBom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
173-
var utf8Bom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: true);
174-
using (StreamReader sr = new(fileInfo.FullName, utf8NoBom, detectEncodingFromByteOrderMarks: true))
175-
{
176-
xDoc = XDocument.Load(sr);
177-
encoding = sr.CurrentEncoding;
178-
}
179-
180-
}
181-
catch (Exception ex)
182-
{
183-
Log.Error($"Failed to load '{fileInfo.FullName}'. {ex}");
184-
return;
185-
}
186-
187-
if (IsXmlMalformed(xDoc, fileInfo.FullName))
139+
if (IsXmlMalformed(xDoc, filePath))
188140
{
189141
return;
190142
}
191143

192-
DocsType docsType = new DocsType(fileInfo.FullName, xDoc, xDoc.Root!, encoding);
144+
DocsType docsType = new(filePath, xDoc, xDoc.Root!, encoding);
193145

194146
bool add = false;
195147
bool addedAsInterface = false;
@@ -208,7 +160,6 @@ private void LoadFile(FileInfo fileInfo)
208160
// Interface files start with I, and have an 2nd alphabetic character
209161
addedAsInterface = docsType.Name.Length >= 2 && docsType.Name[0] == 'I' && docsType.Name[1] >= 'A' && docsType.Name[1] <= 'Z';
210162
add |= addedAsInterface;
211-
212163
}
213164

214165
bool containsAllowedAssembly = docsType.AssemblyInfos.Any(assemblyInfo =>
@@ -246,13 +197,13 @@ private void LoadFile(FileInfo fileInfo)
246197
{
247198
foreach (XElement xeMember in xeMembers.Elements("Member"))
248199
{
249-
DocsMember member = new DocsMember(fileInfo.FullName, docsType, xeMember);
200+
DocsMember member = new(filePath, docsType, xeMember);
250201
totalMembersAdded++;
251202
Members.TryAdd(member.DocId, member); // is it OK this encounters duplicates?
252203
}
253204
}
254205

255-
string message = $"Type '{docsType.DocId}' added with {totalMembersAdded} member(s) included: {fileInfo.FullName}";
206+
string message = $"Type '{docsType.DocId}' added with {totalMembersAdded} member(s) included: {filePath}";
256207
if (addedAsInterface)
257208
{
258209
Log.Magenta("[Interface] - " + message);
@@ -268,7 +219,15 @@ private void LoadFile(FileInfo fileInfo)
268219
}
269220
}
270221

271-
private bool IsXmlMalformed(XDocument? xDoc, string fileName)
222+
private static bool HasAllowedDirName(DirectoryInfo dirInfo) =>
223+
!Configuration.ForbiddenBinSubdirectories.Contains(dirInfo.Name) && !dirInfo.Name.EndsWith(".Tests", StringComparison.InvariantCultureIgnoreCase);
224+
225+
private static bool HasAllowedFileName(FileInfo fileInfo) =>
226+
!fileInfo.Name.StartsWith("ns-") &&
227+
fileInfo.Name != "index.xml" &&
228+
fileInfo.Name != "_filter.xml";
229+
230+
private static bool IsXmlMalformed(XDocument? xDoc, string fileName)
272231
{
273232
if (xDoc == null)
274233
{

‎src/PortToDocs/src/libraries/IntelliSenseXml/IntelliSenseXmlCommentsContainer.cs

Lines changed: 12 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
using System.Diagnostics.CodeAnalysis;
77
using System.IO;
88
using System.Linq;
9-
using System.Xml;
109
using System.Xml.Linq;
1110

1211
/*
@@ -36,30 +35,12 @@ internal class IntelliSenseXmlCommentsContainer
3635
{
3736
private Configuration Config { get; set; }
3837

39-
private XDocument? xDoc = null;
40-
4138
// The IntelliSense xml files do not separate types from members, like ECMA xml files do - Everything is a member.
4239
public Dictionary<string, IntelliSenseXmlMember> Members = new();
4340

44-
public IntelliSenseXmlCommentsContainer(Configuration config)
45-
{
46-
Config = config;
47-
}
48-
49-
public void CollectFiles()
50-
{
51-
Log.Info("Looking for IntelliSense xml files...");
52-
53-
foreach (FileInfo fileInfo in EnumerateFiles())
54-
{
55-
LoadFile(fileInfo, printSuccess: true);
56-
}
57-
58-
Log.Success("Finished looking for IntelliSense xml files.");
59-
Log.Line();
60-
}
41+
public IntelliSenseXmlCommentsContainer(Configuration config) => Config = config;
6142

62-
private IEnumerable<FileInfo> EnumerateFiles()
43+
internal IEnumerable<FileInfo> EnumerateFiles()
6344
{
6445
foreach (DirectoryInfo dirInfo in Config.DirsIntelliSense)
6546
{
@@ -85,19 +66,9 @@ private IEnumerable<FileInfo> EnumerateFiles()
8566
}
8667
}
8768

88-
private void LoadFile(FileInfo fileInfo, bool printSuccess)
69+
internal void LoadIntellisenseXmlFile(XDocument xDoc, string filePath)
8970
{
90-
try
91-
{
92-
xDoc = XDocument.Load(fileInfo.FullName);
93-
}
94-
catch (Exception ex)
95-
{
96-
Log.Error($"Failed to load '{fileInfo.FullName}'. {ex}");
97-
return;
98-
}
99-
100-
if (!TryGetAssemblyName(xDoc, fileInfo.FullName, out string? assembly))
71+
if (!TryGetAssemblyName(xDoc, filePath, out string? assembly))
10172
{
10273
return;
10374
}
@@ -107,15 +78,15 @@ private void LoadFile(FileInfo fileInfo, bool printSuccess)
10778
{
10879
foreach (XElement xeMember in xeMembers.Elements("member"))
10980
{
110-
IntelliSenseXmlMember member = new IntelliSenseXmlMember(xeMember, assembly);
81+
IntelliSenseXmlMember member = new(xeMember, assembly);
11182

112-
if (Config.IncludedAssemblies.Any(included => member.Assembly.StartsWith(included)) &&
113-
!Config.ExcludedAssemblies.Any(excluded => member.Assembly.StartsWith(excluded)))
83+
if (Config.IncludedAssemblies.Any(included => member.Assembly.StartsWith(included, StringComparison.InvariantCultureIgnoreCase)) &&
84+
!Config.ExcludedAssemblies.Any(excluded => member.Assembly.StartsWith(excluded, StringComparison.InvariantCultureIgnoreCase)))
11485
{
11586
// No namespaces provided by the user means they want to port everything from that assembly
11687
if (!Config.IncludedNamespaces.Any() ||
117-
(Config.IncludedNamespaces.Any(included => member.Namespace.StartsWith(included)) &&
118-
!Config.ExcludedNamespaces.Any(excluded => member.Namespace.StartsWith(excluded))))
88+
(Config.IncludedNamespaces.Any(included => member.Namespace.StartsWith(included, StringComparison.InvariantCultureIgnoreCase)) &&
89+
!Config.ExcludedNamespaces.Any(excluded => member.Namespace.StartsWith(excluded, StringComparison.InvariantCultureIgnoreCase))))
11990
{
12091
totalAdded++;
12192
Members.TryAdd(member.Name, member); // is it OK this encounters duplicates?
@@ -124,14 +95,14 @@ private void LoadFile(FileInfo fileInfo, bool printSuccess)
12495
}
12596
}
12697

127-
if (printSuccess && totalAdded > 0)
98+
if (totalAdded > 0)
12899
{
129-
Log.Success($"{totalAdded} IntelliSense xml member(s) added from xml file '{fileInfo.FullName}'");
100+
Log.Success($"{totalAdded} IntelliSense xml member(s) added from xml file '{filePath}'");
130101
}
131102
}
132103

133104
// Verifies the file is properly formed while attempting to retrieve the assembly name.
134-
private bool TryGetAssemblyName(XDocument? xDoc, string fileName, [NotNullWhen(returnValue: true)] out string? assembly)
105+
private static bool TryGetAssemblyName(XDocument? xDoc, string fileName, [NotNullWhen(returnValue: true)] out string? assembly)
135106
{
136107
assembly = null;
137108

‎src/PortToDocs/src/libraries/ToDocsPorter.cs

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33

44
using System;
55
using System.Collections.Generic;
6+
using System.IO;
67
using System.Linq;
8+
using System.Text;
79
using System.Xml.Linq;
810
using ApiDocsSync.Libraries.Docs;
911
using ApiDocsSync.Libraries.IntelliSenseXml;
@@ -32,19 +34,76 @@ public ToDocsPorter(Configuration config)
3234

3335
}
3436

35-
public void Start()
37+
public void CollectFiles()
3638
{
37-
IntelliSenseXmlComments.CollectFiles();
39+
Log.Info("Looking for IntelliSense xml files...");
40+
foreach (FileInfo fileInfo in IntelliSenseXmlComments.EnumerateFiles())
41+
{
42+
XDocument? xDoc = null;
43+
try
44+
{
45+
xDoc = XDocument.Load(fileInfo.FullName);
46+
}
47+
catch (Exception ex)
48+
{
49+
Log.Error($"Failed to load '{fileInfo.FullName}'. {ex}");
50+
}
51+
52+
if (xDoc != null)
53+
{
54+
IntelliSenseXmlComments.LoadIntellisenseXmlFile(xDoc, fileInfo.FullName);
55+
}
56+
}
57+
Log.Success("Finished looking for IntelliSense xml files.");
58+
Log.Line();
3859

60+
Log.Info("Looking for Docs xml files...");
61+
foreach (FileInfo fileInfo in DocsComments 10000 .EnumerateFiles())
62+
{
63+
XDocument? xDoc = null;
64+
Encoding? encoding = null;
65+
try
66+
{
67+
var utf8NoBom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
68+
var utf8Bom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: true);
69+
using (StreamReader sr = new(fileInfo.FullName, utf8NoBom, detectEncodingFromByteOrderMarks: true))
70+
{
71+
xDoc = XDocument.Load(sr);
72+
encoding = sr.CurrentEncoding;
73+
}
74+
}
75+
catch (Exception ex)
76+
{
77+
Log.Error($"Failed to load '{fileInfo.FullName}'. {ex}");
78+
}
79+
80+
if (xDoc != null && encoding != null)
81+
{
82+
DocsComments.LoadDocsFile(xDoc, fileInfo.FullName, encoding);
83+
}
84+
}
85+
Log.Success("Finished looking for Docs xml files.");
86+
Log.Line();
87+
}
88+
89+
public void LoadIntellisenseXmlFile(XDocument xDoc, string filePath) =>
90+
IntelliSenseXmlComments.LoadIntellisenseXmlFile(xDoc, filePath);
91+
92+
public void LoadDocsFile(XDocument xDoc, string filePath, Encoding encoding) =>
93+
DocsComments.LoadDocsFile(xDoc, filePath, encoding);
94+
95+
public void Start()
96+
{
3997
if (!IntelliSenseXmlComments.Members.Any())
4098
{
4199
Log.Error("No IntelliSense xml comments found.");
100+
return;
42101
}
43102

44-
DocsComments.CollectFiles();
45103
if (!DocsComments.Types.Any())
46104
{
47105
Log.Error("No Docs Type APIs found.");
106+
return;
48107
}
49108

50109
PortMissingComments();

0 commit comments

Comments
 (0)
0