API Features documented from source code: the endpoint header

Aperta
  • Qualcosa non va?
#110 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
12/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
markdown, python, typescript
Ambito
backend-api-design, documentation, tooling

Direzione di ricerca

Start with the PageObject header section of docs/reference/authoring-formats.md and the Feature entry in docs/reference/glossary.md, since the proposed endpoint header copies that model. The first task is the spike, an operator-run survey of how ABSA repositories define endpoints and document contracts, and it is not a code change for a newcomer. Done means the spike reports a shape inventory and confirms or corrects the header design.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

type:epic
Background

A project documented in source code cannot document an API Feature today. Source-code headers exist only for
.feature files (User Story, Functionality) and PageObjects (the UI Feature), and living-doc-collector-gh's
doc-source mode reads PageObjects from .ts files only. The canon therefore sends API Features to GitHub Issues or
Azure DevOps, and a feature_dependencies target in a source-code project gives UNRESOLVED_RELATION, which is
expected today (docs/reference/glossary.md, Feature).

A design was drafted in 2026-09 and deferred:

  • a LIVING DOC — comment block directly above the endpoint or handler definition, never at the top of a file, any
    number per file;
  • the PageObject model: one full header per API Feature, cross-reference headers (parent-feat:) on the others;
  • new keys endpoint: and handler:, not route: and page-object: (clarity over reuse);
  • no stub-reason:, and no rule on how many Functionalities one endpoint has; the author decides.

A spike comes first and may change it. Its first finding: atum-service defines endpoints as Tapir values inside an
object, not as annotated methods, so "above the method" is not general enough.

Goals
  • A backend service documents its API Features in its own source code, next to the endpoints.
  • doc-source mines the header from the file types the spike names, and the Feature's endpoints reach the documents.
  • feature_dependencies resolve in a source-code project.
  • The agentic layer writes and maintains the header, and keeps feature_dependencies on the Feature.
Subtasks

In landing order. Each child is drafted when the previous one has merged.

  • living-doc (Spike form): a survey across ABSA repositories, run on local clones plus internal ones as an
    operator run that reports a shape inventory only. It covers the languages and file types, how an endpoint or
    event handler is defined (annotations, route tables, Tapir values), the contract documentation already in use
    (OpenAPI and others), the comment forms per file type, and discovery and exclusions. It ends with the header
    design confirmed or corrected.
  • living-doc: the canon. The endpoint header in docs/reference/authoring-formats.md and the glossary, an
    example in docs/examples/, and examples_check rules for it.
  • living-doc agentic layer: skills write and update the header, and feature_dependencies moves onto the
    Feature, with evals.
  • living-doc-utilities: the parser for the header and an EndpointRef beside PageRef, plus the rendering
    rules for endpoints; released as a minor.
  • living-doc-collector-gh: doc-source reads more file types and mines the header.
  • living-doc-toolkit and living-doc-generator-markdown: endpoints carried and rendered, if the contract
    change needs it.
  • living-doc-testbed: an API Feature in source code. living-doc: snapshots, a milestone run and the
    release.
Related / References
  • docs/reference/glossary.md (Feature, feature_dependencies, surface_type), docs/reference/authoring-formats.md
    (PageObject header: full and cross-reference).
  • living-doc-utilities docs/authoring/parsers.md.
Lingua principale
Python
Stelle
0
Fork
0
Merge medio
6h 14m
PR unite (30g)
27

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di AbsaOSS/living-doc

Tutte le issue di AbsaOSS/living-doc

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.