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

summaryrefslogtreecommitdiffhomepage
path: root/apps/api/Program.cs
diff options
context:
space:
mode:
authorLeitwolf112026-10-03 18:27:22 +0300
committerLeitwolf112026-10-03 18:27:22 +0300
commitb1cf9a3bea0c81c1cb3ed2e0ddce2b9a56e175ef (patch)
tree134f15d6734c4e98d5b38121645a8e72c687ac8e /apps/api/Program.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 'apps/api/Program.cs')
-rw-r--r--apps/api/Program.cs5
1 files changed, 5 insertions, 0 deletions
diff --git a/apps/api/Program.cs b/apps/api/Program.cs
index 0b71d06..5f6a7a5 100644
--- a/apps/api/Program.cs
+++ b/apps/api/Program.cs
@@ -82,4 +82,9 @@ app.MapAccountEndpoints();
app.Run();
+/// <summary>Entry point of the Progmaweb account API.</summary>
+/// <remarks>
+/// The top-level statements configure the services, the request pipeline and the routes. The class is declared so
+/// that the integration tests can start the application in memory.
+/// </remarks>
public partial class Program;