Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Dokumentazzjoni Awtomatika

Lezzjoni 8 / 20 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Iddokumenta Mingħajr Ma Tinterrompi l-Iżvilupp
  2. Dokumentazzjoni Inline: JSDoc u Kummenti
  3. Ġenerazzjoni ta’ README
  4. Dokumentazzjoni tal-API
  5. Dokumentazzjoni tal-Arkitettura
  6. Aġġornament tad-Dokumentazzjoni Eżistenti
  7. Awtomazzjoni permezz ta’ AGENTS.md
  8. Punti Ewlenin

Iddokumenta Mingħajr Ma Tinterrompi l-Iżvilupp

Kulħadd jaqbel li d-dokumentazzjoni hija meħtieġa, madankollu kważi ħadd ma jiktebha. Għaliex? Għax il-kitba sseħħ fl-agħar mument possibbli: il-funzjonalità tkun lesta, u l-attenzjoni diġà marret ‘il quddiem. Codex iċaqlaq dan l-ispiża. Janalizza l-kodiċi hekk kif jeżisti u jipproduċi dokumentazzjoni sħiħa u aġġornata li tkun allinjata mal-implimentazzjoni attwali. Din il-fedeltà hija l-fattur deċiżiv: dokumentazzjoni inventata tikkawża aktar ħsara minn paġna vojta għax toħloq kunfidenza falza.

Dokumentazzjoni Inline: JSDoc u Kummenti

L-aktar dokumentazzjoni kkonsultata tidher eżatt fit-tooltip tal-editur, preċiżament fejn tqum il-mistoqsija.

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

Hawnhekk hawn x’jipproduċi Codex għal funzjoni ta’ kalkolu tal-prezz:

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

Żewġ biċċiet ta’ informazzjoni hawnhekk jiswew aktar minn kollox l-ieħor: l-unità—ċenteżimi, mhux ewro—u l-eċċezzjoni mħejjija għal valuri negattivi. Dawn huma eżattament iż-żewġ affarijiet li żviluppatur ġeneralment jiskopri fil-produzzjoni, wara li jiffattura lill-klijenti għaxar darbiet inqas milli maħsub. Codex estrajjhom mill-implimentazzjoni, mhux minn mudell ġeneriku ta’ kummenti.

Ġenerazzjoni ta’ README

Għal proġett ġdid, jew għal README li sar fittizju minħabba d-devjazzjoni, elenka x’għandu jkun kapaċi jagħmel il-qarrej darba jispiċċa jaqra.

"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 jiddependi fuq package.json, fajls ta’ konfigurazzjoni, u s-siġra tad-direttorju attwali biex jipproduċi dokument li jirrifletti l-istat attwali tal-proġett. L-istruzzjoni “mingħajr valuri” mhix kapriċċ: mingħajrha, aġent li għadu kemm qara .env.example mimli sew jista’ b’mod ferħan jikkopja valuri li inti ma tridx jidhru f’fajl verżjonat.

Dokumentazzjoni tal-API

Għal API REST, l-aktar dokumentazzjoni effiċjenti f’termini ta’ spiża hija dik li għodod oħra jistgħu jikkunsmaw mingħajr intervent uman.

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

Kollox huwa estratt mill-kodiċi: mogħdijiet tar-rotot, metodi HTTP, skemi ta’ validazzjoni, u tipi ta’ rispons. L-ispeċifikazzjoni li tirriżulta għalhekk hija fedeli għall-implimentazzjoni, u tippermetti lill-konsumaturi tiegħek jidderivaw klijent ittajpjat jew kollezzjoni ta’ testijiet mingħajr ma jistaqsuk mistoqsija waħda.

Dokumentazzjoni tal-Arkitettura

Id-deċiżjonijiet tal-arkitettura rari jiġu miktuba. Meta jkunu, jiddeskrivu l-intenzjoni inizjali aktar mir-realtà tliet snin wara. Itlob lil Codex jifformalizza x’jeżisti verament fil-kodiċi.

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

Dan id-dokument għandu benefiċċju sekondarju mhux mistenni: billi jiddeskrivi d-dipendenzi tal-moduli hekk kif huma verament, jesponi akkoppjamenti li ħadd ma kien ammetta—bħas-servizz tal-fatturazzjoni li jimporta utilità mill-modulu tal-awtentikazzjoni.

Aġġornament tad-Dokumentazzjoni Eżistenti

Dokumentazzjoni skaduta hija agħar minn ebda dokumentazzjoni għax titlef il-ħin b’awtorità.

"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 jiffaċċja kull affermazzjoni fir-README mal-kodiċi attwali u jikkoreġi l-inkonsistenzi. Skeda din il-kompitu perjodikament, bħal qabel kull rilaxx, minflok ma tiskopri n-neċessità tagħha l-jum li fih impjegat ġdid isib li l-ebda wieħed mill-kumandi ta’ installazzjoni ma jaħdem.

Awtomazzjoni permezz ta’ AGENTS.md

Biex tieqaf tittratta d-dokumentazzjoni bħala xogħol separat, agħmilha restrizzjoni permanenti tal-proġett.

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

B’dawn it-tliet regoli, kull kompitu ta’ żvilupp iġorr l-aġġornament tad-dokumentazzjoni tiegħu stess. Il-vojt bejn il-kodiċi u d-deskrizzjoni jieqaf jikber silenzjożament, li huwa l-uniku mod sostenibbli biex tirbaħ din il-battalja.

Punti Ewlenin

  • Codex jiġġenera dokumentazzjoni fedeli għall-kodiċi attwali, mhux inventata
  • Id-dokumentazzjoni inline (JSDoc) hija l-aktar utli għax-xogħol ta’ kuljum
  • Codex jista’ jipproduċi READMEs, speċifikazzjonijiet OpenAPI, u dokumentazzjoni tal-arkitettura
  • Uża lil Codex biex tiskopri u tikkoreġi dokumentazzjoni skaduta
  • Żid regoli ta’ dokumentazzjoni f’AGENTS.md biex tawtomatizza l-proċess