On pourrait avoir un fichier Markdown, tout comme ce que tu as, mais qui, au lieu d'appeler des binaires, appelle des méthodes et des fonctions et teste leurs résultats. Directement lisible en tant que doc.
Mais pour que ça marche, il faut un moyen d'appeler les tests depuis le système de tests (unitaires) du projet, en fonction du langage utilisé. Faut que le "test runner" trouve les tests dans les fichiers markdown. Pour ça, il faut probablement générer des fichiers de tests habituellement écrits à la main, ou être embarquable en tant que bibliothèque appelée par le "test runner".
Bon après, peut-être que ça a beaucoup de sens d'avoir un système comme celui que tu proposes pour appeler des binaires parce que la documentation est celle à destination des utilisateurs finaux / utilisatrices finales, mais que ça n'a pas tant d'intérêt que ça pour des tests unitaires et de la doc pour les devs, qui peut se permettre d'être plus technique, avec plus facilement du code mis en avant.
D'un autre côté, qui n'a jamais cherché comment on utilise un code pas suffisamment documenté en regardant ses tests unitaires, quand une doc lisible aurait été plus appréciable ? Naïvement, un bbt pour les tests unitaires pourrait sembler intéressant. Ça pourrait permettre d'ajouter une rubrique d'exemples d'utilisation pour chaque fonction à cette page par exemple, avec le résultat attendu. Pour certain projets, l'utilisateur final est un·e dev, par exemple pour les frameworks. Peut-être que ça devrait être un outil complémentaire à part, ça résout probablement un problème plus ou moins différent et demande une manière de faire différente.
En tout cas merci pour tes réponses, bien cool ta doc comparables.md!
[^] # Re: Documentation exécutable, expect, tests unitaires
Posté par raphj (site web personnel) . En réponse au journal Documenter ou tester, il faut trancher (j'ai pas trouvé de rime avec choisir...). Évalué à 3. Dernière modification le 06 février 2025 à 12:45.
On pourrait avoir un fichier Markdown, tout comme ce que tu as, mais qui, au lieu d'appeler des binaires, appelle des méthodes et des fonctions et teste leurs résultats. Directement lisible en tant que doc.
Mais pour que ça marche, il faut un moyen d'appeler les tests depuis le système de tests (unitaires) du projet, en fonction du langage utilisé. Faut que le "test runner" trouve les tests dans les fichiers markdown. Pour ça, il faut probablement générer des fichiers de tests habituellement écrits à la main, ou être embarquable en tant que bibliothèque appelée par le "test runner".
Bon après, peut-être que ça a beaucoup de sens d'avoir un système comme celui que tu proposes pour appeler des binaires parce que la documentation est celle à destination des utilisateurs finaux / utilisatrices finales, mais que ça n'a pas tant d'intérêt que ça pour des tests unitaires et de la doc pour les devs, qui peut se permettre d'être plus technique, avec plus facilement du code mis en avant.
D'un autre côté, qui n'a jamais cherché comment on utilise un code pas suffisamment documenté en regardant ses tests unitaires, quand une doc lisible aurait été plus appréciable ? Naïvement, un bbt pour les tests unitaires pourrait sembler intéressant. Ça pourrait permettre d'ajouter une rubrique d'exemples d'utilisation pour chaque fonction à cette page par exemple, avec le résultat attendu. Pour certain projets, l'utilisateur final est un·e dev, par exemple pour les frameworks. Peut-être que ça devrait être un outil complémentaire à part, ça résout probablement un problème plus ou moins différent et demande une manière de faire différente.
En tout cas merci pour tes réponses, bien cool ta doc
comparables.md!