Transclusione di simboli
Incorpora codice live nella tua documentazione per nome, non per numero di riga. Modifica il sorgente e la documentazione si aggiorna automaticamente.
# Incorpora una funzione per nome
![[auth.py#validate_token]]Ohai estrae la funzione validate_token da auth.py e la renderizza inline con evidenziazione della sintassi. Quando la funzione cambia, la documentazione si aggiorna automaticamente.
Perché è importante
La documentazione tradizionale invecchia. Copi e incolli il codice nel markdown, il codice evolve e improvvisamente la tua documentazione ti sta mentendo. La transclusione di simboli risolve questo problema trattando i file sorgente come l'unica fonte di verità.
A differenza dei riferimenti al numero di riga che si rompono ad ogni refactoring, la transclusione di simboli utilizza il parsing AST per trovare il codice tramite il suo nome effettivo—funzioni, classi, struct, costanti. Rinomina un file, riorganizza il codice, aggiungi nuovi metodi—finché il nome del simbolo esiste, la documentazione resta accurata.
Casi d'uso
Documentazione API
Fai riferimento alle firme delle funzioni effettive, non ad approssimazioni scritte a mano che vanno fuori sincronia.
Architecture Decision Records
Incorpora il codice che stai discutendo negli ADR. Gli esempi restano aggiornati man mano che la codebase evolve.
Guide di onboarding
Mostra ai nuovi sviluppatori come funziona l'autenticazione con codice live di cui possono fidarsi che corrisponda al repository.
Code review
Estrai funzioni specifiche in un riepilogo markdown per revisione e discussione asincrona.
Tutorial
Illustra implementazioni reali. I lettori possono fidarsi che gli esempi di codice siano sempre aggiornati.
Runbook
Incorpora la configurazione esatta o lo script a cui il team operativo deve fare riferimento durante gli incidenti.
Linguaggi supportati
Oltre 30 linguaggi tramite parsing AST con Tree-sitter. Anche chiavi JSON, percorsi YAML e tabelle TOML.
Pronto a provare documentazione che non invecchia mai?
Scarica per Mac