GEWIS / sudosos-backend / 25162023571

92%

push

github

docs: enrich catalogue/* modules with prose and per-type descriptions (#882)

* docs(container): add comprehensive entity prose documentation

Expand the Container entity JSDoc with prose explaining sellers and
revenue flow, the revision pattern, the public/private visibility
model, and the link to sub-transactions. Use the module-qualified
@link syntax so cross-module references resolve in TypeDoc.

* chore(typedoc): strip swagger @param noise, extend block tags

Add a small TypeDoc plugin that drops swagger-jsdoc dotted @param
names (e.g. @param {type} name.query.required) from controllers
before the validator sees them. These tags are load-bearing for
Swagger generation but not valid TSDoc, and previously produced
around a thousand "@param not used" warnings.

Also extend the blockTags list to preserve TypeDoc's defaults while
adding the swagger-jsdoc tags (@typedef, @property, @route, etc.)
and our custom documentation tags (@promote, @index).

* docs: document cross-module @link syntax and fix stale refs

Because typedoc-plugin-merge-modules places each @module in its own
container, a bare {@link SymbolName} cannot resolve across modules.
Document the module-qualified form — {@link moduleName!Symbol | label}
— in docs/content/typedoc.md, and fix two existing stale references
in the authenticator entities so they now resolve.

* docs: fix stale JSDoc tags in controllers and services

Clean up the remaining TypeDoc warnings after the swagger-param
stripping plugin narrowed the field to real drift:

- Remove legacy @constructor tags from non-constructor methods in
  AuthenticationController and AuthenticationService.
- Fix @inhertidoc typo to @inheritDoc in InvoiceController.
- Collapse stale per-field @param lists on methods that take a
  single destructured options object (BalanceService.getBalances,
  DebtorService.{calculateFinesOnDate,handOutFines,sendFineWarnings},
  EventService.getShiftSelectedCount, RBACService.{getRoles,getRoleUsers})
  in... (continued)

1824 of 2244 branches covered (81.28%)

Branch coverage included in aggregate %.

9385 of 10336 relevant lines covered (90.8%)

1020.03 hits per line