Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Automaatne dokumentatsioon

Õppetund 8 / 20 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Dokumenteerimine arendust katkestamata
  2. Reasisene dokumentatsioon: JSDoc ja kommentaarid
  3. README faili genereerimine
  4. API dokumentatsioon
  5. Arhitektuuri dokumentatsioon
  6. Olemasoleva dokumentatsiooni uuendamine
  7. Automatiseerimine faili AGENTS.md kaudu
  8. Peamised punktid

Dokumenteerimine arendust katkestamata

Kõik on nõus, et dokumentatsioon on vajalik, kuid peaaegu keegi ei kirjuta seda. Miks? Sest kirjutamine toimub kõige halvemal võimalikul hetkel: funktsioon on valmis ja tähelepanu on juba mujale liikunud. Codex nihutab seda kulu. See analüüsib olemasolevat koodi ja loob tervikliku, ajakohase dokumentatsiooni, mis vastab tegelikule teostusele. See täpsus on otsustav tegur: väljamõeldud dokumentatsioon teeb rohkem kahju kui tühi leht, sest see tekitab vale kindlustunde.

Reasisene dokumentatsioon: JSDoc ja kommentaarid

Kõige enam kasutatav dokumentatsioon ilmub otse redaktori tööriistavihjesse, täpselt sinna, kus küsimus tekib.

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

Siin on see, mida Codex toodab hinna arvutamise funktsiooni jaoks:

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

Siin on kaks teabetükki, mis kaaluvad üles kõik muu: ühik – sendid, mitte eurod – ja negatiivsete väärtuste korral visatav erind. Need on täpselt need kaks asja, mille arendaja tavaliselt tootmiskeskkonnas avastab, pärast seda, kui on klientidelt kümme korda vähem arvestanud kui plaanis. Codex ekstraheeris need teostusest, mitte üldisest kommentaarimallist.

README faili genereerimine

Uue projekti puhul või kui README on lahknevuse tõttu muutunud fiktsiooniks, loetle üles, mida lugeja peab pärast lugemist suutma teha.

"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 tugineb failile package.json, konfiguratsioonifailidele ja tegelikule kataloogipuule, et luua dokument, mis peegeldab projekti praegust seisundit. Juhis „ilma väärtusteta“ ei ole kapriis: ilma selleta võib agent, kes on just lugenud hästi täidetud .env.example faili, rõõmsalt kopeerida väärtused, mida sa versioonitud failis näha ei soovi.

API dokumentatsioon

REST API puhul on kuluefektiivseim dokumentatsioon see, mida teised tööriistad saavad tarbida ilma inimese sekkumiseta.

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

Kõik ekstraheeritakse koodist: marsruutide rajad, HTTP meetodid, valideerimisskeemid ja vastuse tüübid. Saadud spetsifikatsioon on seetõttu teostusele truu, võimaldades sinu tarbijatel tuletada tüübitud kliendi või testide kogumiku, ilma et nad peaksid sulle ühtegi küsimust esitama.

Arhitektuuri dokumentatsioon

Arhitektuuriotsuseid kirjutatakse harva üles. Kui seda tehakse, kirjeldavad need algset kavatsust, mitte reaalsust kolm aastat hiljem. Palu Codexil formaliseerida see, mis koodis tegelikult eksisteerib.

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

Sellel dokumendil on ootamatu kõrvalkasu: kirjeldades moodulite sõltuvusi nii, nagu need tegelikult on, paljastab see sidususi, mida keegi pole tunnistanud – näiteks arveldusteenus, mis impordib utiliidi autentimismoodulist.

Olemasoleva dokumentatsiooni uuendamine

Aegunud dokumentatsioon on halvem kui dokumentatsiooni puudumine, sest see raiskab aega autoriteetsuse varjus.

"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 seab iga README väite vastamisi tegeliku koodiga ja parandab lahknevused. Planeeri see ülesanne perioodiliselt, näiteks enne iga väljalaset, selle asemel, et avastada selle vajalikkust päeval, mil uus töötaja avastab, et ükski paigalduskäsk ei tööta.

Automatiseerimine faili AGENTS.md kaudu

Selleks, et lõpetada dokumentatsiooni käsitlemist eraldi kohustusena, tee sellest projekti püsiv piirang.

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

Nende kolme reegliga kannab iga arendusülesanne endas ka oma dokumentatsiooni uuendamist. Lõhe koodi ja kirjelduse vahel lõpetab vaikselt laienemise, mis on ainus jätkusuutlik viis selles lahingus võitmiseks.

Peamised punktid

  • Codex genereerib dokumentatsiooni, mis on truu tegelikule koodile, mitte väljamõeldud
  • Reasisene dokumentatsioon (JSDoc) on igapäevatööks kõige kasulikum
  • Codex suudab luua README-faile, OpenAPI spetsifikatsioone ja arhitektuuri dokumentatsiooni
  • Kasuta Codexit aegunud dokumentatsiooni tuvastamiseks ja parandamiseks
  • Lisa dokumentatsioonireeglid faili AGENTS.md, et protsessi automatiseerida