Documents/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

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

# Tala website API

Reference documentation of the website's ASP.NET Core API, generated by DocFX from the XML documentation comments
of `backend/Progmasoft.Tala.Website.Api`. The reference includes internal and private members: it documents the code
for the people who maintain it.

Build and check it from the repository root:

```sh
dotnet tool restore
dotnet docfx Documents/api/docfx.json --warningsAsErrors
dotnet run Documents/api/CheckDocumentation.cs -- Documents/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, internal and private members included.

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