Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/docs/api/CheckDocumentation.cs
diff options
context:
space:
mode:
authorLeitwolf112026-10-03 18:27:22 +0300
committerLeitwolf112026-10-03 18:27:22 +0300
commitb1cf9a3bea0c81c1cb3ed2e0ddce2b9a56e175ef (patch)
tree134f15d6734c4e98d5b38121645a8e72c687ac8e /docs/api/CheckDocumentation.cs
parente9eb2812a47b075c82a138db7f43cc08cccf072a (diff)
downloadprogmaweb-b1cf9a3bea0c81c1cb3ed2e0ddce2b9a56e175ef.tar.gz
Require documentation for every item of the API reference
The DocFX gate only failed on a broken link or an unresolved reference. DocFX does not report a declaration without a comment, and the API had none, so the gate passed over a reference with no descriptions at all. The gate now has three parts: - DocFX still builds the reference with warnings as errors. - The API project compiles its XML documentation. With warnings as errors already on, an undocumented public declaration or a wrong cref now fails the build. - docs/api/CheckDocumentation.cs reads the metadata DocFX generated and fails when a namespace, type or member has no summary. This covers internal and private members, which the compiler does not check. It runs as a file-based .NET program, so the gate needs no tool beyond the SDK. It refuses to pass when the metadata is missing or defines nothing. To satisfy the gate, every declaration of apps/api has documentation comments, 131 reference items in all, and the two namespaces are described by overwrite files in docs/api/namespaces. Only comment lines were added to the C# sources; no statement changed. docs/api/filterConfig.yml leaves generator-written code out of the reference: the generated regular-expression namespace, and the one partial method whose generated half replaces the comment of its declaration. Verified locally: the solution builds with no warnings, the 23 API tests pass, DocFX builds with no warnings and the coverage check passes. Removing one summary and one namespace file made the check fail and name both.
Diffstat (limited to 'docs/api/CheckDocumentation.cs')
-rw-r--r--docs/api/CheckDocumentation.cs118
1 files changed, 118 insertions, 0 deletions
diff --git a/docs/api/CheckDocumentation.cs b/docs/api/CheckDocumentation.cs
new file mode 100644
index 0000000..f359661
--- /dev/null
+++ b/docs/api/CheckDocumentation.cs
@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
+
+// Documentation coverage gate of the API reference.
+//
+// DocFX builds a reference from whatever comments exist and does not report a declaration that has none. This
+// program reads the metadata DocFX generated and fails when a namespace, type or member is undocumented, so the
+// reference cannot contain an entry without a description.
+//
+// Usage, after `dotnet docfx metadata docs/api/docfx.json`:
+//
+// dotnet run docs/api/CheckDocumentation.cs -- docs/api
+//
+// The exit code is 0 when everything is documented, 1 when something is not, and 2 when the metadata is missing.
+
+using System.Text.RegularExpressions;
+
+string root = args.Length > 0 ? args[0] : "docs/api";
+string referenceDirectory = Path.Combine(root, "reference");
+string namespaceDirectory = Path.Combine(root, "namespaces");
+
+if (!Directory.Exists(referenceDirectory))
+{
+ Console.Error.WriteLine($"No metadata in '{referenceDirectory}'. Run 'dotnet docfx metadata' first.");
+ return 2;
+}
+
+// A namespace has no declaration that could carry a comment. Its description is an overwrite file named after it.
+HashSet<string> describedNamespaces = Directory.Exists(namespaceDirectory)
+ ? Directory.EnumerateFiles(namespaceDirectory, "*.md")
+ .Where(HasDescription)
+ .Select(path => Path.GetFileNameWithoutExtension(path)!)
+ .ToHashSet(StringComparer.Ordinal)
+ : [];
+
+List<string> undocumented = [];
+int checkedItems = 0;
+
+foreach (string file in Directory.EnumerateFiles(referenceDirectory, "*.yml").Order(StringComparer.Ordinal))
+{
+ if (Path.GetFileName(file) == "toc.yml")
+ {
+ continue;
+ }
+
+ // The items a file defines come first; the `references` section after them repeats names of other files.
+ string text = File.ReadAllText(file).ReplaceLineEndings("\n");
+ int references = text.IndexOf("\nreferences:", StringComparison.Ordinal);
+ string definitions = references < 0 ? text : text[..references];
+
+ foreach (string item in ItemStart().Split(definitions).Skip(1))
+ {
+ string uid = item[..item.IndexOf('\n')].Trim();
+ string type = ItemType().Match(item) is { Success: true } match ? match.Groups[1].Value : "Item";
+ checkedItems++;
+
+ bool documented = type == "Namespace"
+ ? describedNamespaces.Contains(uid)
+ : ItemSummary().IsMatch(item);
+ if (!documented)
+ {
+ undocumented.Add($"{type} {uid}");
+ }
+ }
+}
+
+if (checkedItems == 0)
+{
+ Console.Error.WriteLine($"The metadata in '{referenceDirectory}' defines nothing; the gate would pass vacuously.");
+ return 2;
+}
+
+if (undocumented.Count != 0)
+{
+ Console.Error.WriteLine($"{undocumented.Count} of {checkedItems} API items have no documentation:");
+ foreach (string entry in undocumented)
+ {
+ Console.Error.WriteLine($" {entry}");
+ }
+
+ Console.Error.WriteLine("Add a <summary> to each declaration, or a file in docs/api/namespaces for a namespace.");
+ return 1;
+}
+
+Console.WriteLine($"All {checkedItems} API items are documented.");
+return 0;
+
+// An overwrite file describes its namespace when it has text after its front matter and comment header.
+static bool HasDescription(string path)
+{
+ string text = File.ReadAllText(path).ReplaceLineEndings("\n");
+ int frontMatterEnd = text.IndexOf("\n---", 3, StringComparison.Ordinal);
+ if (!text.StartsWith("---\n", StringComparison.Ordinal) || frontMatterEnd < 0)
+ {
+ return false;
+ }
+
+ string body = HtmlComment().Replace(text[(frontMatterEnd + 4)..], string.Empty);
+ return text[..frontMatterEnd].Contains($"uid: {Path.GetFileNameWithoutExtension(path)}", StringComparison.Ordinal)
+ && !string.IsNullOrWhiteSpace(body);
+}
+
+internal static partial class Program
+{
+ // Every defined item starts with its identifier at the left margin.
+ [GeneratedRegex(@"^- uid: ", RegexOptions.Multiline)]
+ private static partial Regex ItemStart();
+
+ [GeneratedRegex(@"^ type: (\w+)", RegexOptions.Multiline)]
+ private static partial Regex ItemType();
+
+ // A summary with content: text on the same line, or a block scalar followed by an indented line.
+ [GeneratedRegex(@"^ summary: (?:[^\s>|].*|[>|][-+]?\n \S)", RegexOptions.Multiline)]
+ private static partial Regex ItemSummary();
+
+ [GeneratedRegex(@"<!--.*?-->", RegexOptions.Singleline)]
+ private static partial Regex HtmlComment();
+}