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

mainroot / docs / api / index.md

1.5 KiB · Raw · Log

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

# 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.