Automatinė dokumentacija
Šiame puslapyje
Dokumentavimas netrukdydamas kūrimui
Visi sutaria, kad dokumentacija yra būtina, tačiau beveik niekas jos nerašo. Kodėl? Nes rašymas vyksta netinkamiausiu metu: funkcija jau baigta, o dėmesys jau nukreiptas kitur. „Codex“ perkelia šią naštą. Jis analizuoja esamą kodą ir sukuria išsamią, atnaujintą dokumentaciją, tiksliai atitinkančią realų įgyvendinimą. Šis tikslumas yra lemiamas veiksnys: išgalvota dokumentacija daro daugiau žalos nei tuščias puslapis, nes sukelia klaidingą pasitikėjimą.
Įterptinė dokumentacija: JSDoc ir komentarai
Dažniausiai naudojama dokumentacija atsiranda tiesiai redaktoriaus patarime, būtent ten, kur kyla klausimas.
"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."
Štai ką „Codex“ sugeneruoja kainos skaičiavimo funkcijai:
/**
* 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 {
// ...
}
Čia dvi informacijos dalys vertos daugiau už visa kita: matavimo vienetas – centai, o ne eurai – ir išimtis, išmetama neigiamoms reikšmėms. Tai būtent tie du dalykus, kuriuos kūrėjas paprastai atranda gamyboje, jau apskaičiavęs klientams dešimt kartų mažiau nei planuota. „Codex“ išgavo juos tiesiai iš įgyvendinimo, o ne iš bendro komentarų šablono.
README failo generavimas
Naujam projektui arba README failui, kuris dėl pokyčių tapo fikcija, nurodykite, ką skaitytojas turi gebėti padaryti perskaitęs dokumentaciją.
"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“ remiasi package.json, konfigūracijos failais ir realia katalogų struktūra, kad sukurtų dokumentą, atspindintį dabartinę projekto būklę. Instrukcija „be reikšmių“ nėra užgaida: be jos agentas, perskaitęs gerai užpildytą .env.example, gali lengvai nukopijuoti reikšmes, kurių nenorite matyti versijuojamame faile.
API dokumentacija
REST API atveju ekonomiškiausia dokumentacija yra ta, kurią kiti įrankiai gali naudoti be žmogaus įsikišimo.
"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."
Viskas išgaunama iš kodo: maršrutų keliai, HTTP metodai, validacijos schemos ir atsakymų tipai. Todėl gauta specifikacija yra ištikima įgyvendinimui, leidžianti vartotojams sugeneruoti tipizuotą klientą arba testų rinkinį neuždavus jums nė vieno klausimo.
Architektūros dokumentacija
Architektūros sprendimai retai užrašomi. O kai tai daroma, jie aprašo pradinį sumanymą, o ne realybę po trejų metų. Paprašykite „Codex“ formalizuoti tai, kas iš tikrųjų egzistuoja kode.
"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"
Šis dokumentas turi netikėtą antrinę naudą: aprašydamas modulių priklausomybes tokias, kokios jos iš tikrųjų yra, jis atskleidia sąsajas, kurių niekas nepripažino – pavyzdžiui, atsiskaitymų servisas, importuojantis pagalbinę funkciją iš autentifikavimo modulio.
Esamos dokumentacijos atnaujinimas
Pasenusi dokumentacija yra blogiau nei jokios dokumentacijos, nes ji eikvoja laiką ir daro tai autoritetingai.
"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“ patikrina kiekvieną README teiginį prieš faktinį kodą ir ištaiso neatitikimus. Suplanuokite šią užduotį periodiškai, pavyzdžiui, prieš kiekvieną leidimą, o ne laukite dienos, kai naujas darbuotojas atras, kad nė viena diegimo komanda neveikia.
Automatizavimas naudojant AGENTS.md
Kad nustotumėte laikyti dokumentaciją atskira pareiga, paverskite ją nuolatiniu projekto reikalavimu.
## 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
Laikydamiesi šių trijų taisyklių, kiekviena kūrimo užduotis automatiškai apima ir dokumentacijos atnaujinimą. Atotrūkis tarp kodo ir aprašymo nustoja tyliai didėti, ir tai yra vienintelis tvarus būdas laimėti šią kovą.
Svarbiausi punktai
- „Codex“ generuoja dokumentaciją, ištikimą realiam kodui, o neišgalvotą
- Įterptinė dokumentacija (JSDoc) yra naudingiausia kasdieniam darbui
- „Codex“ gali kurti README, OpenAPI specifikacijas ir architektūros dokumentaciją
- Naudokite „Codex“ nustatyti ir ištaisyti pasenusią dokumentaciją
- Įtraukite dokumentacijos taisykles į AGENTS.md, kad automatizuotumėte procesą