Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

Describe the stricter documentation gate in the guides

The guides merged from main still said that the DocFX gate does not require
documentation comments. With this branch it does, so:

- docs/DEVELOPMENT.md and README.md list the coverage check next to the
  DocFX command and say what fails the gate.
- docs/LIMITATIONS.md no longer lists missing documentation comments as a
  limitation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Commit
08a076a3f880764462410a0b2f855d5bdfba1066
Author
Leitwolf11 ·
Parents
01ddcb6071eb

Files · Download .tar.gz

Changes

 README.md           |  4 +++-
 docs/DEVELOPMENT.md | 10 +++++++---
 docs/LIMITATIONS.md |  6 ------
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 8132611..d5b05eb 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,7 @@ dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration
 dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release --coverlet --coverlet-output-format cobertura
 dotnet tool restore
 dotnet docfx docs/api/docfx.json --warningsAsErrors
+dotnet run docs/api/CheckDocumentation.cs -- docs/api
 ```
 
 Frontend tests exercise the published locale contract and account/ViGet metadata without starting a production service.
@@ -103,7 +104,8 @@ The frontend LCOV and API Cobertura reports are retained as one-day artifacts, t
 jobs. Only those upload jobs receive `id-token: write`; dependency installation, builds, and tests do not receive OIDC
 permissions, and fork-originated pull requests skip the upload jobs. CodeQL and Codacy provide static analysis;
 Dependabot proposes dependency updates without merging them automatically. The DocFX command builds the API reference
-and fails on a broken link or an unresolved reference. [Development](docs/DEVELOPMENT.md) explains each check.
+and fails on a broken link or an unresolved reference; the check after it fails when any item of the reference has no
+description. [Development](docs/DEVELOPMENT.md) explains each check.
 
 ## License
 
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 66822de..c5da810 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -122,11 +122,15 @@ version, so a local run and CI use the same tool.
 ```text
 dotnet tool restore
 dotnet docfx docs/api/docfx.json --warningsAsErrors
+dotnet run docs/api/CheckDocumentation.cs -- docs/api
 ```
 
-or `just api-docs`. The output goes to `docs/api/_site`, which is ignored by Git. A broken link or an unresolved
-reference fails the build. The gate does not yet require documentation comments on the C# declarations; see
-[Known limitations](LIMITATIONS.md).
+or `just api-docs`. The output goes to `docs/api/_site`, which is ignored by Git.
+
+The gate fails on a broken link or an unresolved reference, on a public declaration without a documentation comment,
+and on any namespace, type or member of the reference that has no summary, internal and private ones included. A new
+declaration therefore needs its `<summary>` in the same change. [The API reference page](api/index.md) describes the
+three parts of the gate and how a namespace is described.
 
 ## Conventions
 
diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md
index 107c48f..b08d334 100644
--- a/docs/LIMITATIONS.md
+++ b/docs/LIMITATIONS.md
@@ -68,12 +68,6 @@ that route moves here, the legacy process has to keep running.
 The authentication rate limit is counted in the memory of one API process, by client address. It is reset by a
 restart and would not be shared between several instances.
 
-## Documentation comments are not required
-
-The DocFX gate fails on a broken link or an unresolved reference. It does not report a declaration without a
-documentation comment, and most C# declarations have none, so the generated reference lists members without
-descriptions.
-
 ## The Hebrew text has not been reviewed by a native speaker
 
 The Hebrew translation was written and revised without a native reader. It may contain wording a native speaker would