Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Automatická dokumentácia

Lekcia 8 z 20 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Dokumentácia bez prerušenia vývoja
  2. Vnorená dokumentácia: JSDoc a komentáre
  3. Generovanie súboru README
  4. Dokumentácia API
  5. Dokumentácia architektúry
  6. Aktualizácia existujúcej dokumentácie
  7. Automatizácia prostredníctvom AGENTS.md
  8. Kľúčové poznatky

Dokumentácia bez prerušenia vývoja

Všetci súhlasia, že dokumentácia je nevyhnutná, no takmer nikto ju nepíše. Prečo? Lebo k písaniu dochádza v najnevhodnejší možný čas: funkcia je hotová a pozornosť sa už presunula inam. Codex tento náklad presúva. Analyzuje kód tak, ako existuje, a vytvára úplnú, aktuálnu dokumentáciu, ktorá zodpovedá skutočnej implementácii. Táto vernosť je rozhodujúcim faktorom: vymyslená dokumentácia spôsobuje viac škody než prázdna stránka, pretože vyvoláva falošnú dôveru.

Vnorená dokumentácia: JSDoc a komentáre

Najčastejšie konzultovaná dokumentácia sa zobrazuje priamo v bublinovej nápovede editora, presne tam, kde vzniká otázka.

"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."

Tu je výsledok, ktorý Codex vyprodukoval pre funkciu výpočtu ceny:

/**
 * 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 {
  // ...
}

Dve informácie tu majú väčšiu váhu než všetko ostatné: jednotka – centy, nie eurá – a výnimka vyvolaná pri záporných hodnotách. Presne toto sú dve veci, ktoré vývojár zistí až v produkcii, potom, čo zákazníkom účtoval desaťkrát menej, než mal. Codex tieto údaje extrahoval priamo z implementácie, nie zo všeobecnej šablóny komentárov.

Generovanie súboru README

Pre nový projekt alebo pre súbor README, ktorý sa v dôsledku driftu stal fikciou, definuj, čo musí čitateľ vedieť urobiť po jeho prečítaní.

"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 sa opiera o súbor package.json, konfiguračné súbory a skutočnú štruktúru adresárov, aby vytvoril dokument odrážajúci aktuálny stav projektu. Pokyn „bez hodnôt“ nie je rozmar: bez neho by agent, ktorý práve čítal dobre vyplnený súbor .env.example, mohol pokojne skopírovať hodnoty, ktoré nechceš mať vo verzionovanom súbore.

Dokumentácia API

Pre REST API je najnákladovo efektívnejšou dokumentáciou tá, ktorú môžu iné nástroje spotrebovať bez ľudského zásahu.

"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."

Všetko sa extrahuje priamo z kódu: cesty trás, HTTP metódy, schémy validácie a typy odpovedí. Výsledná špecifikácia je preto verná implementácii, čo umožňuje tvojim konzumentom odvodiť typovaného klienta alebo kolekciu testov bez toho, aby ti položili jedinú otázku.

Dokumentácia architektúry

Rozhodnutia o architektúre sa zriedka zapisujú. Ak áno, opisujú pôvodný zámer, nie realitu o tri roky neskôr. Požiadaj Codex, aby formalizoval to, čo skutočne existuje v kóde.

"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"

Tento dokument má neočakávaný vedľajší benefit: opisom závislostí medzi modulmi tak, ako skutočne sú, odhaľuje väzby, ktoré nikto neuznal – napríklad fakt, že fakturačná služba importuje utilitu z autentifikačného modulu.

Aktualizácia existujúcej dokumentácie

Zastaraná dokumentácia je horšia než žiadna, pretože plytvá časom a pôsobí pritom autoritatívne.

"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 konfrontuje každé tvrdenie v súbore README so skutočným kódom a opravuje nezrovnalosti. Naplánuj si túto úlohu pravidelne, napríklad pred každým vydaním, namiesto toho, aby si na jej nevyhnutnosť prišiel v deň, keď nový zamestnanec zistí, že žiadny z inštalačných príkazov nefunguje.

Automatizácia prostredníctvom AGENTS.md

Aby si prestal považovať dokumentáciu za samostatnú povinnosť, urob z nej trvalé obmedzenie projektu.

## 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 týmito tromi pravidlami so sebou každá vývojová úloha nesie aj aktualizáciu dokumentácie. Priepasť medzi kódom a popisom sa prestane ticho zväčšovať, čo je jediný udržateľný spôsob, ako túto bitku vyhrať.

Kľúčové poznatky

  • Codex generuje dokumentáciu vernú skutočnému kódu, nie vymyslenú
  • Vnorená dokumentácia (JSDoc) je najužitočnejšia pre dennú prácu
  • Codex dokáže vytvoriť súbory README, špecifikácie OpenAPI a dokumentáciu architektúry
  • Použi Codex na detekciu a opravu zastaranej dokumentácie
  • Pridaj pravidlá pre dokumentáciu do súboru AGENTS.md, aby si automatizoval tento proces