Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Automatikus dokumentáció

8. lecke 20 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Dokumentálás a fejlesztés megszakítása nélkül
  2. Beágyazott dokumentáció: JSDoc és megjegyzések
  3. README generálása
  4. API dokumentáció
  5. Architektúra dokumentáció
  6. Meglévő dokumentáció frissítése
  7. Automatizálás az AGENTS.md segítségével
  8. Főbb megállapítások

Dokumentálás a fejlesztés megszakítása nélkül

Mindenki egyetért abban, hogy a dokumentáció szükséges, mégis szinte senki nem írja meg. Miért? Mert az írásra a legrosszabbkor kerül sor: a funkció elkészült, és a figyelem már máshol jár. A Codex eltolja ezt a költséget. Elemzi a kódot annak jelenlegi állapotában, és teljes, naprakész dokumentációt készít, amely hűen tükrözi a tényleges megvalósítást. Ez a hűség a döntő tényező: a kitalált dokumentáció több kárt okoz, mint az üres lap, mert hamis biztonságérzetet kelt.

Beágyazott dokumentáció: JSDoc és megjegyzések

A leggyakrabban használt dokumentáció közvetlenül a szerkesztő eszköztippjében jelenik meg, pontosan ott, ahol a kérdés felmerül.

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

Íme, mit hoz létre a Codex egy árszámító függvényhez:

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

Ebben a két információ többet ér minden másnál: a mértékegység (cent, nem euró) és a negatív értékek esetén dobott kivétel. Ezek pontosan azok a dolgok, amelyeket a fejlesztő általában éles környezetben fedez fel, miután az ügyfeleket a tervezett összeg tizedrészével számlázták meg. A Codex ezeket a megvalósításból nyerte ki, nem pedig egy általános megjegyzéssablonból.

README generálása

Egy új projektnél, vagy ha a README a drift miatt már fikcióvá vált, sorold fel, mit kell tudnia csinálnia az olvasónak az elolvasás után.

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

A Codex a package.json-ra, a konfigurációs fájlokra és a tényleges könyvtárszerkezetre támaszkodik, hogy olyan dokumentumot hozzon létre, amely a projekt aktuális állapotát tükrözi. A „értékek nélkül“ utasítás nem szeszély: enélkül egy ügynök, amely éppen elolvasott egy jól kitöltött .env.example fájlt, vidáman másolhatna olyan értékeket, amelyeket nem szeretnél, ha verziókezelt fájlban szerepelnének.

API dokumentáció

REST API esetén a legköltséghatékonyabb dokumentáció az, amelyet más eszközök emberi beavatkozás nélkül képesek fogyasztani.

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

Minden a kódból származik: útvonalak, HTTP metódusok, validációs sémák és válasz típusok. Az így kapott specifikáció ezért hű a megvalósításhoz, lehetővé téve a fogyasztóid számára, hogy típusos klienst vagy tesztgyűjteményt vezessenek le belőle anélkül, hogy egyetlen kérdést is feltennének neked.

Architektúra dokumentáció

Az architektúrális döntéseket ritkán jegyzik le. Ha mégis, azok a kezdeti szándékot írják le, nem pedig a három évvel későbbi valóságot. Kérd meg a Codexet, hogy formalizálja azt, ami ténylegesen létezik a kódban.

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

Ennek a dokumentumnak van egy váratlan mellékhaszna: a modulfüggőségek valós leírásával feltár olyan csatolásokat, amelyeket senki nem ismert el – például, hogy a számlázási szolgáltatás importál egy segédprogramot a hitelesítési modulból.

Meglévő dokumentáció frissítése

Az elavult dokumentáció rosszabb, mint a semmilyen, mert tekintéllyel pazarolja az időt.

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

A Codex szembesíti a README minden állítását a tényleges kóddal, és kijavítja az inkonzisztenciákat. Ütemezd ezt a feladatot időszakosan, például minden kiadás előtt, ahelyett, hogy csak akkor döbbennél rá a szükségességére, amikor egy új munkatárs rájön, hogy a telepítési parancsok egyike sem működik.

Automatizálás az AGENTS.md segítségével

Ahhoz, hogy a dokumentációt ne külön feladatként kezeld, tedd a projekt állandó korlátozásává.

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

Ezzel a három szabállyal minden fejlesztési feladat magában hordozza a saját dokumentációs frissítését. A kód és a leírás közötti szakadék不再 növekszik csendben, és ez az egyetlen fenntartható módja ennek a harcnak a megnyerésére.

Főbb megállapítások

  • A Codex a tényleges kódhoz hű dokumentációt generál, nem kitaláltat
  • A beágyazott dokumentáció (JSDoc) a napi munka szempontjából a leghasznosabb
  • A Codex képes README, OpenAPI specifikációk és architektúra dokumentáció létrehozására
  • Használd a Codexet az elavult dokumentáció észlelésére és javítására
  • Vegyél fel dokumentációs szabályokat az AGENTS.md fájlba a folyamat automatizálásához