docs/api/index.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<!--
SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
-->

# Progmaweb API

Reference documentation of the Progmaweb account service, generated by DocFX
from the XML documentation comments of `apps/api`.

The service is an application, not a library, so most of its types are
internal. The reference includes them: it documents the code for the people
who maintain it.

Build and check it from the repository root:

```sh
dotnet tool restore
dotnet docfx docs/api/docfx.json --warningsAsErrors
dotnet run docs/api/CheckDocumentation.cs -- docs/api
```

## What the gate requires

Three things fail the check, locally and in CI:

- **A broken link or an unresolved reference.** DocFX runs with every warning treated as an error.
- **An undocumented public declaration or a wrong `cref`.** The API project compiles its XML documentation, and the
  build treats the compiler's documentation warnings as errors.
- **Any undocumented item of the reference.** `CheckDocumentation.cs` reads the metadata DocFX generated and fails
  when a namespace, type or member has no summary. This covers internal and private members too, which the compiler
  does not check.

A namespace has no declaration that could hold a comment. Its description is a file in `namespaces/`, named after
the namespace.

`filterConfig.yml` lists what is left out of the reference: code written by a source generator, which nobody
maintains and which cannot carry documentation. Do not add an entry there to get past the gate; write the summary.