Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Samodejna dokumentacija

Lekcija 8 od 20 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Dokumentiranje brez prekinitve razvoja
  2. Vrstična dokumentacija: JSDoc in komentarji
  3. Ustvarjanje datoteke README
  4. Dokumentacija API-ja
  5. Arhitekturna dokumentacija
  6. Posodabljanje obstoječe dokumentacije
  7. Avtomatizacija prek datoteke AGENTS.md
  8. Ključne ugotovitve

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