Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-027 — Stratégie de documentation polyglotte (ABI C et bindings multi-langages)

Statut : Accepté — mise en œuvre différée à la couche 2.

Catégorie : Documentation / Architecture (couche 2 — ABI & polyglotte).

Contexte

La couche 0 (air-sys-types, air-sys-syscall) est du Rust interne (publish = false), sans ABI C publique : sa documentation (rustdoc) s’adresse à des développeurs Rust. Or la vision d’Air est polyglotte dès le départ : le modèle d’objet et les services sont exposés en ABI C à partir de la couche 2 (cf. ADR-002), consommables sans glue depuis C, Swift, Python, Ruby (libair-runtime.so, libair-aircom.so). Cette ABI est un contrat stable (garantie 10 ans, outillée — Principe 8, ADR-012).

Il manque une décision sur comment documenter cette surface pour les développeurs non-Rust, de façon cohérente, testée et maintenable, sans maintenir à la main une documentation parallèle qui dériverait.

Décision

  1. Source unique de vérité. La documentation C / polyglotte est générée depuis le code Rust (commentaires /// sur l’API pub extern "C"), jamais rédigée en parallèle. Le code et sa doc ne font qu’un (cohérent avec le workflow « doc d’abord » du projet).
  2. Outillage C (socle). cbindgen génère le header .h (types #[repr(C)] + fonctions extern "C") en reportant les commentaires de doc ; le header est à la fois artefact de doc et artefact de contrat ABI (réutilisable par l’outillage de stabilité — air-abi-check, air-symver).
  3. Multi-langages (à instruire). Pour l’ambition Swift/Python/Ruby, évaluer Diplomat (bindings + doc idiomatiques multi-langages depuis une API Rust) ; le choix définitif fera l’objet d’un ADR dédié au moment de la couche 2, sous la règle des 80 % de dépendances (ADR-024).
  4. Intégration docbook. Une section « API C / Polyglotte » du mdBook est produite par scripts/build-docs.sh (cbindgen → header annoté → Doxygen ou équivalent → markdown embarqué), aux côtés de la référence rustdoc. Un hook est réservé dans build-docs.sh dès maintenant.
  5. Périmètre / calendrier. Mise en œuvre différée à la couche 2 : tant qu’aucune crate n’expose d’ABI C, rien n’est généré. La couche 0 reste du Rust interne. Convention à tenir dès la première crate C-ABI : son API publique porte des commentaires de doc de qualité « export ».

Conséquences

  • + Doc C/polyglotte toujours synchrone du code ; développeurs non-Rust traités en citoyens de première classe ; le header généré sert aussi de contrat ABI.
  • + Pas de documentation parallèle à maintenir (zéro dérive).
  • − Introduit des dépendances d’outillage de doc (cbindgen, Doxygen, éventuellement Diplomat) à auditer sous ADR-024 au moment de la couche 2.
  • − Impose une discipline de commentaires « export-quality » sur l’API C-ABI.

Alternatives écartées

  • Doc C rédigée à la main : rejetée (dérive inévitable vs le code).
  • ABI C dès la couche 0 : rejetée (sans valeur — la libc le fait déjà — et contraire à l’architecture en couches).
  • Pas de doc C dédiée : rejetée (contredit la vision polyglotte, ADR-002).

Addendum (2026-06-25) — format de rendu + doc des OBLIGATIONS du développeur C

Précise la mise en œuvre (clôt le « Doxygen ou équivalent » de la Décision §4) et grave les exigences de contenu orientées développeur C.

A. Format de rendu — Doxygen (choix arrêté)

  • Référence par symbole = Doxygen sur le header généré par cbindgen. Raisons : standard du monde C (le dev C s’attend à le lire) ; génère HTML + pages man (man air_log_open) ; langage-agnostique, mature, déterministe (version pinnée, HTML_TIMESTAMP=NO — ADR-025). Écartés : Sphinx+Breathe (toolchain Python plus lourde), rustdoc (non lu par les devs C).
  • Header cbindgen COMMITTÉ (comme le .rs capnpc d’ADR-040) : c’est un contrat ABI — committé, régénéré par le mainteneur, et diffé en CI pour détecter toute dérive d’ABI (consommé par air-abi-check/air-symver). Versions cbindgen/Doxygen pinnées.
  • Intégration mdBook : section « API C / Polyglotte » (Décision §4), FR + EN (convention doc du projet).

B. Doc des OBLIGATIONS du développeur C (exigence de CONTENU, gravée)

La doc par-symbole ne suffit pas : des guides conceptuels mdBook (FR+EN) doivent expliquer comment utiliser la lib et quelles sont les obligations de l’appelant. Couverture obligatoire :

  1. Mise en route : header à inclure, lien (-lair-base), versionnement/ABI (ADR-012).
  2. Modèle d’erreurs : AirError/AirStatus (ADR-019) — comment tester, lire, propager ; conventions de valeur de retour et de nullité ; aucune panic ne traverse l’ABI.
  3. Propriété mémoire & cycle de vie (LE point critique). Pour chaque type complexe/ opaque, la doc DOIT énoncer explicitement, sans ambiguïté :
    • qui alloue / qui libère, et avec quelle fonction (air_*_free / air_*_release) ;
    • transfert de propriété sur RETOUR : un type complexe retourné est-il possédé par l’appelant (→ il doit le libérer) ou emprunté/partagé (→ il ne doit pas le libérer) — règle uniforme +1 retours / +0 arguments du modèle d’objet (air-object) ;
    • types complexes passés en ARGUMENT : empruntés (+0), l’appelant garde la propriété ; l’appelé ne libère pas, ne conserve pas de référence au-delà de l’appel (sauf doc explicite) ;
    • chaînes / buffers / out-paramètres : qui possède la mémoire, durée de validité, taille, encodage (octets vs UTF-8) ;
    • refcompté : retain/release appariés ; secrets : effacement (zeroize) à charge de qui. → Objectif : un dev C sait toujours s’il doit libérer un type, et comment.
  4. Thread-safety par type : politiques déclarées (Immutable / MainThreadOnly / ThreadSafe, air-object) — ce qui est appelable depuis quel thread.
  5. Exemples C compilables (testés autant que possible — un échantillon dans la suite ABI).

Discipline gravée : chaque fonction pub extern "C" porte un commentaire /// « export-quality » qui inclut sa clause de propriété (retour possédé/emprunté ; arguments empruntés ; fonction de libération). cbindgen la reporte dans le header ; Doxygen la rend. La doc de propriété n’est donc pas un guide séparé qui dérive : elle naît du commentaire de chaque symbole + est synthétisée dans le guide « propriété mémoire ».

C. Portée

Mis en œuvre à la première passe ABI C (à commencer par air-base-lib → libair-base.so). Les dépendances de doc (cbindgen, Doxygen) auditées sous ADR-024 à ce moment.