Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Automatická dokumentace

Lekce 8 z 20 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Dokumentace bez přerušování vývoje
  2. Vložená dokumentace: JSDoc a komentáře
  3. Generování souboru README
  4. Dokumentace API
  5. Dokumentace architektury
  6. Aktualizace stávající dokumentace
  7. Automatizace prostřednictvím AGENTS.md
  8. Klíčové poznatky

Dokumentace bez přerušování vývoje

Všichni se shodují, že dokumentace je nezbytná, přesto ji téměř nikdo nepíše. Proč? Protože k psaní dochází v ten nejnevhodnější okamžik: funkce je hotová a pozornost se již přesunula jinam. Codex tento náklad přesouvá. Analyzuje kód tak, jak existuje, a vytváří úplnou, aktuální dokumentaci, která odpovídá skutečné implementaci. Tato věrnost je rozhodujícím faktorem: vymyšlená dokumentace napáchá více škody než prázdná stránka, protože vyvolává falešnou důvěru.

Vložená dokumentace: JSDoc a komentáře

Nejpoužívanější dokumentace se zobrazuje přímo v bublinové nápovědě editoru, přesně tam, kde vyvstane 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."

Zde je výsledek, který Codex vytvořil pro funkci 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 {
  // ...
}

Dvě informace zde mají větší cenu než vše ostatní: jednotka – centy, nikoliv eura – a výjimka vyhazovaná pro záporné hodnoty. Přesně toto jsou dvě věci, které vývojář obvykle zjistí až v produkci, poté, co zákazníkům naúčtoval desetkrát méně, než měl v úmyslu. Codex tyto údaje extrahoval přímo z implementace, nikoliv ze šablony obecného komentáře.

Generování souboru README

U nového projektu nebo u souboru README, který se vlivem driftu stal fikcí, definuj, co musí být čtenář schopen udělat, jakmile dokončí čtení.

"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 opírá o soubor package.json, konfigurační soubory a skutečnou strukturu adresářů, aby vytvořil dokument odrážející aktuální stav projektu. Pokyn „bez hodnot“ není rozmar: bez něj by agent, který právě četl dobře vyplněný soubor .env.example, mohl s klidem zkopírovat hodnoty, které nechceš mít ve verzovaném souboru.

Dokumentace API

U REST API je nejnákladově efektivnější dokumentace ta, kterou mohou jiné nástroje spotřebovat bez lidské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še je extrahováno z kódu: cesty tras, HTTP metody, schémata validace a typy odpovědí. Výsledná specifikace je proto věrná implementaci, což umožňuje tvým konzumentům odvodit typovaného klienta nebo sadu testů, aniž by ti museli položit jedinou otázku.

Dokumentace architektury

Rozhodnutí o architektuře jsou zřídka zapisována. Pokud ano, popisují původní záměr, nikoliv realitu o tři roky později. Požádej Codex, aby formalizoval to, co skutečně existuje v kódu.

"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čekávaný vedlejší přínos: popisem závislostí modulů tak, jak skutečně jsou, odhaluje vazby, které nikdo neuznával – například fakt, že fakturační služba importuje utilitu z modulu autentizace.

Aktualizace stávající dokumentace

Zastaralá dokumentace je horší než žádná, protože plýtvá časem s autoritou.

"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é tvrzení v souboru README se skutečným kódem a opravuje nesrovnalosti. Naplánuj si tento úkol pravidelně, například před každým vydáním, abys nemusel zjistit jeho nutnost až ve chvíli, kdy nový zaměstnanec zjistí, že žádný z instalačních příkazů nefunguje.

Automatizace prostřednictvím AGENTS.md

Aby přestal být dokumentace považována za samostatnou povinnost, učiň z ní trvalé omezení 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 třemi pravidly nese každý vývojový úkol svou vlastní aktualizaci dokumentace. Rozdíl mezi kódem a popisem přestane tiše narůstat, což je jediný udržitelný způsob, jak tuto bitvu vyhrát.

Klíčové poznatky

  • Codex generuje dokumentaci věrnou skutečnému kódu, nikoliv vymyšlenou
  • Vložená dokumentace (JSDoc) je nejužitečnější pro denní práci
  • Codex dokáže vytvářet soubory README, specifikace OpenAPI a dokumentaci architektury
  • Použij Codex k detekci a opravě zastaralé dokumentace
  • Přidej pravidla pro dokumentaci do souboru AGENTS.md pro automatizaci procesu