|
| 1 | +using System.Xml.Linq; |
| 2 | +using Microsoft.CodeAnalysis; |
| 3 | +using Microsoft.CodeAnalysis.CSharp; |
| 4 | +using Microsoft.CodeAnalysis.CSharp.Syntax; |
| 5 | +using Path = System.IO.Path; |
| 6 | + |
| 7 | +namespace Docs.Utilities; |
| 8 | + |
| 9 | +public static class DocsApi |
| 10 | +{ |
| 11 | + // Published binaries define the API. Tagged source supplies comments missing from the packages. |
| 12 | + public static void Prepare(string source, string assemblies) |
| 13 | + { |
| 14 | + var references = Directory.GetFiles(assemblies, "*.dll") |
| 15 | + .Select(p => MetadataReference.CreateFromFile(p)).ToArray(); |
| 16 | + var inventory = new List<string>(); |
| 17 | + var routes = new List<string>(); |
| 18 | + foreach (var assembly in references.Where(r => Path.GetFileName(r.FilePath!).StartsWith("GitVersion", StringComparison.OrdinalIgnoreCase))) |
| 19 | + { |
| 20 | + var name = Path.GetFileNameWithoutExtension(assembly.FilePath!); |
| 21 | + var metadata = CSharpCompilation.Create("Inventory", references: references); |
| 22 | + var symbol = metadata.GetAssemblyOrModuleSymbol(assembly) as IAssemblySymbol |
| 23 | + ?? throw new InvalidOperationException($"Could not inspect {name}."); |
| 24 | + var exported = Types(symbol.GlobalNamespace).Where(Public).ToArray(); |
| 25 | + inventory.AddRange(exported.Select(t => t.GetDocumentationCommentId()!).Where(id => id is not null)); |
| 26 | + routes.AddRange(exported.Select(t => t.ContainingNamespace.ToDisplayString() + "/" + t.MetadataName.Replace('`', '_') + "/index.html")); |
| 27 | + SupplementComments(source, assemblies, references, assembly, name); |
| 28 | + } |
| 29 | + File.WriteAllLines(Path.Combine(assemblies, "public-types.txt"), inventory.Order(StringComparer.Ordinal)); |
| 30 | + File.WriteAllLines(Path.Combine(assemblies, "public-type-routes.txt"), routes.Order(StringComparer.Ordinal)); |
| 31 | + } |
| 32 | + |
| 33 | + private static void SupplementComments(string source, string assemblies, PortableExecutableReference[] references, PortableExecutableReference assembly, string name) |
| 34 | + { |
| 35 | + var project = Path.Combine(source, "src", name == "gitversion" ? "GitVersion.App" : name); |
| 36 | + if (!Directory.Exists(project)) |
| 37 | + { |
| 38 | + return; |
| 39 | + } |
| 40 | + |
| 41 | + var trees = Directory.GetFiles(project, "*.cs", SearchOption.AllDirectories) |
| 42 | + .Where(p => !Path.GetRelativePath(project, p).Split(Path.DirectorySeparatorChar).Any(s => s is "bin" or "obj" or "Templates")) |
| 43 | + .Select(p => CSharpSyntaxTree.ParseText(File.ReadAllText(p), new CSharpParseOptions(documentationMode: DocumentationMode.Diagnose), p)).ToArray(); |
| 44 | + var compilation = CSharpCompilation.Create(name, trees, references.Where(r => r != assembly), |
| 45 | + new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)); |
| 46 | + var path = Path.Combine(assemblies, name + ".xml"); |
| 47 | + var document = File.Exists(path) ? XDocument.Load(path) : new XDocument(new XElement("doc", new XElement("assembly", new XElement("name", name)), new XElement("members"))); |
| 48 | + var members = document.Root!.Element("members")!; |
| 49 | + var existing = members.Elements("member").Select(m => (string?)m.Attribute("name")).ToHashSet(); |
| 50 | + foreach (var tree in trees) |
| 51 | + { |
| 52 | + AddTreeComments(compilation.GetSemanticModel(tree), tree, members, existing); |
| 53 | + } |
| 54 | + |
| 55 | + document.Save(path); |
| 56 | + } |
| 57 | + |
| 58 | + private static void AddTreeComments(SemanticModel model, SyntaxTree tree, XElement members, HashSet<string?> existing) |
| 59 | + { |
| 60 | + foreach (var node in tree.GetRoot().DescendantNodes().Where(n => n is MemberDeclarationSyntax or VariableDeclaratorSyntax)) |
| 61 | + { |
| 62 | + var declared = model.GetDeclaredSymbol(node); |
| 63 | + var id = declared?.GetDocumentationCommentId(); |
| 64 | + if (id is null || existing.Contains(id)) |
| 65 | + { |
| 66 | + continue; |
| 67 | + } |
| 68 | + |
| 69 | + var xml = declared!.GetDocumentationCommentXml(); |
| 70 | + if (string.IsNullOrWhiteSpace(xml)) |
| 71 | + { |
| 72 | + continue; |
| 73 | + } |
| 74 | + |
| 75 | + try { members.Add(XElement.Parse(xml)); existing.Add(id); } |
| 76 | + catch (System.Xml.XmlException e) { throw new InvalidOperationException($"Invalid API comment for {id} in {tree.FilePath}", e); } |
| 77 | + } |
| 78 | + |
| 79 | + } |
| 80 | + |
| 81 | + private static IEnumerable<INamedTypeSymbol> Types(INamespaceOrTypeSymbol parent) |
| 82 | + { |
| 83 | + foreach (var member in parent.GetMembers()) |
| 84 | + { |
| 85 | + if (member is INamedTypeSymbol type) |
| 86 | + { |
| 87 | + yield return type; |
| 88 | + } |
| 89 | + |
| 90 | + if (member is INamespaceOrTypeSymbol container) |
| 91 | + { |
| 92 | + foreach (var child in Types(container)) |
| 93 | + { |
| 94 | + yield return child; |
| 95 | + } |
| 96 | + } |
| 97 | + } |
| 98 | + } |
| 99 | + |
| 100 | + private static bool Public(INamedTypeSymbol type) => type.DeclaredAccessibility == Accessibility.Public |
| 101 | + && !type.Name.Contains('<') && type.ContainingNamespace.ToDisplayString().StartsWith("GitVersion", StringComparison.Ordinal) |
| 102 | + && (type.ContainingType is null || Public(type.ContainingType)); |
| 103 | +} |
0 commit comments