diff options
| author | Leitwolf11 | 2026-10-03 18:42:57 +0300 |
|---|---|---|
| committer | Leitwolf11 | 2026-10-03 18:42:57 +0300 |
| commit | 08a076a3f880764462410a0b2f855d5bdfba1066 (patch) | |
| tree | 5012d38d7dfc1bdc4cf75c3db7772d3fac7a5a4e /docs | |
| parent | 01ddcb6071ebdfb08b5ca40c868420b726f4f225 (diff) | |
| download | progmaweb-ci/docfx-require-documentation.tar.gz | |
Describe the stricter documentation gate in the guidesci/docfx-require-documentation
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>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/DEVELOPMENT.md | 10 | ||||
| -rw-r--r-- | docs/LIMITATIONS.md | 6 |
2 files changed, 7 insertions, 9 deletions
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 |