Samodejna dokumentacija
Na tej strani
Dokumentiranje brez prekinitve razvoja
Vsi se strinjajo, da je dokumentacija nujna, vendar jo skoraj nihče ne piše. Zakaj? Ker pisanje pride ob najslabšem možnem času: funkcionalnost je končana, pozornost pa se je že premaknila naprej. Codex ta strošek premakne. Analizira kodo, kot obstaja, in ustvari popolno, posodobljeno dokumentacijo, ki je usklajena z dejansko implementacijo. Ta zvestoba je odločilni dejavnik: izmišljena dokumentacija povzroči več škode kot prazna stran, ker vzbuja lažno zaupanje.
Vrstična dokumentacija: JSDoc in komentarji
Najpogosteje uporabljena dokumentacija se pojavi neposredno v orodnem namigu urejevalnika, točno tam, kjer se vprašanje porodi.
"Add JSDoc documentation to all exported functions
and types in src/lib/. Include a description,
parameters, return type, and a usage example
for each function."
Tukaj je tisto, kar Codex ustvari za funkcijo izračuna cene:
/**
* Calculates the total price after applying the discount.
*
* @param basePrice - Unit price in cents
* @param quantity - Number of units (minimum 1)
* @param discountPercent - Discount percentage (0-100)
* @returns The total price in cents, rounded to an integer
*
* @example
* calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
*
* @throws {ValidationError} If price or quantity is negative
*/
export function calculateTotal(
basePrice: number,
quantity: number,
discountPercent: number = 0
): number {
// ...
}
Dva podatka tukaj sta vredna vsega drugega: enota – centi, ne evri – in izjema, vržena pri negativnih vrednostih. To sta natanko dve stvari, ki ju razvijalec običajno odkrije šele v produkciji, potem ko je strankam zaračunal desetkrat manj, kot je bilo namenjeno. Codex ju je izvlekel iz implementacije, ne iz splošne predloge za komentarje.
Ustvarjanje datoteke README
Za nov projekt ali za README, ki je zaradi drsenja kode postal fikcija, naštej, kaj mora bralec znati storiti, ko preneha brati.
"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"
Codex se opira na package.json, konfiguracijske datoteke in dejansko drevo imenikov, da ustvari dokument, ki odraža trenutno stanje projekta. Navodilo „brez vrednosti” ni muha: brez njega bi agent, ki je pravkar prebral dobro zapolnjeno .env.example, z veseljem kopiral vrednosti, ki jih ne želiš v datoteki pod nadzorom različic.
Dokumentacija API-ja
Za REST API je najbolj stroškovno učinkovita dokumentacija tista, ki jo druga orodja lahko porabijo brez človekovega posredovanja.
"Analyze all routes in src/api/routes/ and generate
an openapi.yaml file. Include request and response
schemas based on existing TypeScript types and
Zod validations."
Vse je izvlečeno iz kode: poti do rut, metode HTTP, sheme za validacijo in tipi odgovorov. Nastala specifikacija je zato zvesta implementaciji, kar tvojim porabnikom omogoča, da izpeljejo tipiziranega odjemalca ali zbirko testov, ne da bi ti postavili eno samo vprašanje.
Arhitekturna dokumentacija
Odločitve o arhitekturi so redko zapisane. Ko so, opisujejo začetni namen, ne pa realnosti tri leta kasneje. Prosi Codex, naj formalizira tisto, kar dejansko obstaja v kodi.
"Analyze the project architecture and create a
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"
Ta dokument ima nepričakovano stransko korist: z opisovanjem odvisnosti med moduli, kot dejansko so, razkriva sklopitve, ki jih nihče ni priznal – na primer, da storitev za obračunavanje uvaža pripomoček iz modula za avtentikacijo.
Posodabljanje obstoječe dokumentacije
Zastarela dokumentacija je slabša od nobene, ker zapravlja čas s pridihom avtoritete.
"Compare README.md with the current state of the project.
Identify outdated sections (commands that no longer exist,
removed dependencies, incorrect instructions).
Update the README accordingly."
Codex vsako trditev v datoteki README sooči z dejansko kodo in popravi neskladja. To nalogo načrtuj občasno, na primer pred vsako izdajo, namesto da bi nujnost odkril šele dan, ko novi sodelavec ugotovi, da noben od ukazov za namestitev ne deluje.
Avtomatizacija prek datoteke AGENTS.md
Da ne bi več obravnavali dokumentacije kot ločeno opravilo, jo naredi za stalno omejitev projekta.
## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details
S temi tremi pravili vsaka razvojna naloga nosi svojo posodobitev dokumentacije. Razkorak med kodo in opisom se neha tiho širiti, kar je edini trajnosten način, da to bitko dobiš.
Ključne ugotovitve
- Codex ustvarja dokumentacijo, zvesto dejanski kodi, ne izmišljeno
- Vrstična dokumentacija (JSDoc) je najbolj uporabna za vsakodnevno delo
- Codex lahko ustvari README, specifikacije OpenAPI in arhitekturno dokumentacijo
- Uporabi Codex za odkrivanje in popravljanje zastarele dokumentacije
- Dodaj pravila o dokumentaciji v AGENTS.md, da avtomatiziraš proces