Automatska dokumentacija
Na ovoj stranici
Dokumentiranje bez prekida razvoja
Svi se slažu da je dokumentacija nužna, no gotovo je nitko ne piše. Zašto? Zato što se pisanje događa u najgorem mogućem trenutku: značajka je gotova, a pažnja je već usmjerena drugamo. Codex pomiče taj trošak. Analizira kod kakav jest i stvara potpunu, ažurnu dokumentaciju usklađenu sa stvarnom implementacijom. Ta vjernost presudni je čimbenik: izmišljena dokumentacija nanosi više štete od prazne stranice jer ulijeva lažno povjerenje.
Ugradbena dokumentacija: JSDoc i komentari
Najčešće korištena dokumentacija pojavljuje se izravno u alatnom savjetu uređivača, točno ondje gdje se javlja pitanje.
"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."
Evo što Codex proizvodi za funkciju izračuna cijene:
/**
* 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 ovdje vrijede više od svega ostalog: jedinica—centi, a ne euri—i iznimka koja se baca za negativne vrijednosti. To su upravo dvije stvari koje programer obično otkrije u produkciji, nakon što je naplatio kupcima deset puta manje nego što je namjeravao. Codex ih je izvukao iz implementacije, a ne iz predloška generičkog komentara.
Generiranje README datoteke
Za novi projekt ili za README koji je zbog odstupanja postao fikcija, navedi što čitatelj mora moći učiniti nakon što završi s čitanjem.
"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 oslanja na package.json, konfiguracijske datoteke i stvarno stablo direktorija kako bi proizveo dokument koji odražava trenutno stanje projekta. Uputa „bez vrijednosti“ nije hirovitost: bez nje, agent koji je upravo pročitao dobro popunjenu .env.example mogao bi s veseljem kopirati vrijednosti koje ne želiš vidjeti u datoteci pod nadzorom verzija.
Dokumentacija API-ja
Za REST API, najisplativija dokumentacija jest ona koju drugi alati mogu koristiti bez ljudske intervencije.
"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."
Sve se izvlači iz koda: putanje ruta, HTTP metode, sheme validacije i vrste odgovora. Rezultirajuća specifikacija stoga je vjerna implementaciji, omogućujući tvojim korisnicima da izvedu tipiziranog klijenta ili kolekciju testova bez da ti postave ijedno pitanje.
Dokumentacija arhitekture
Odluke o arhitekturi rijetko se zapisuju. Kada se i zapišu, opisuju početnu namjeru, a ne stvarnost tri godine kasnije. Zatraži od Codexa da formalizira ono što stvarno postoji u kodu.
"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"
Ovaj dokument ima neočekivanu sporednu korist: opisujući ovisnosti modula kakve one doista jesu, razotkriva sprege koje nitko nije priznao—poput usluge naplate koja uvozi uslužni program iz modula za autentifikaciju.
Ažuriranje postojeće dokumentacije
Zastarjela dokumentacija gora je od nepostojanja dokumentacije jer gubi vrijeme s autoritetom.
"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 suprotstavlja svaku tvrdnju u README-u stvarnom kodu i ispravlja nedosljednosti. Zakaži ovaj zadatak povremeno, primjerice prije svakog izdanja, umjesto da nužnost toga otkriješ onog dana kada novi suradnik ustanovi da nijedna naredba za instalaciju ne radi.
Automatizacija putem AGENTS.md
Da bi prestao tretirati dokumentaciju kao zaseban teret, učini je trajnim ograničenjem 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 ova tri pravila, svaki zadatak razvoja nosi sa sobom vlastito ažuriranje dokumentacije. Jaz između koda i opisa prestaje se tiho širiti, što je jedini održiv način za pobjedu u ovoj bitci.
Ključne točke
- Codex generira dokumentaciju vjernu stvarnom kodu, a ne izmišljenu
- Ugradbena dokumentacija (JSDoc) najkorisnija je za svakodnevni rad
- Codex može proizvesti README, OpenAPI specifikacije i dokumentaciju arhitekture
- Koristi Codex za otkrivanje i ispravljanje zastarjele dokumentacije
- Dodaj pravila o dokumentaciji u AGENTS.md kako bi automatizirao proces