Doiciméadú Uathoibríoch
Ar an leathanach seo
Doiciméadú Gan Cur isteach ar an bhForbairt
Aontaíonn gach duine go bhfuil doiciméadú riachtanach, ach ní scríobhann beagnach aon duine é. Cén fáth? Tarlaíonn an scríbhneoireacht ag an am is measa: tá an gné críochnaithe, agus tá an aire imithe cheana féin. Aistríonn Codex an costas seo. Déanann sé anailís ar an gcód mar atá sé agus táirgeann sé doiciméadú iomlán, cothrom le dáta, atá ag teacht leis an gcur chun feidhme iarbhír. Is é an dílseacht seo an fachtóir cinntitheach: is mó an dochar a dhéanann doiciméadú cumtha ná leathanach bán toisc go spreagann sé muinín bhréige.
Doiciméadú Inlíne: JSDoc agus Nótaí Trácht
Is é an doiciméadú is minice a chuirtear i gcomhairle ná an ceann a fheictear díreach i leid an eagarthóra, go díreach san áit a dtagann an cheist chun cinn.
"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."
Seo a tháirgeann Codex do fheidhm ríomha praghas:
/**
* 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 {
// ...
}
Tá dhá shonra anseo a bhfuil níos mó luacha iontu ná aon rud eile: an t-aonad—ceinteoirí, seachas eorónna—agus an eisceacht a chaitear le haghaidh luachanna diúltacha. Is iad sin go díreach an dá rud a fhionnann forbróir de ghnáth sa táirgeadh, tar éis billiú a dhéanamh ar chustaiméirí deich n-uaire níos lú ná mar a bhí beartaithe. D’eascair Codex iad ón gcur chun feidhme, ní ó theimpléad nótaí trácht ginearálta.
README a Ghiniúint
I gcás tionscadail nua, nó do README atá tar éis éirí ficseanúil de bharr claonta, déan liosta de na rudaí ar chóir don léitheoir a bheith in ann a dhéanamh nuair a bheidh an léitheoireacht críochnaithe aige.
"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"
Braitheann Codex ar package.json, ar chomhaid chumraíochta, agus ar chrann eolaire iarbhír chun doiciméad a tháirgeadh a léiríonn stádas reatha an tionscadail. Ní capricéad é an treoir “gan luachanna”: gan é, d’fhéadfadh gníomhaire a léigh .env.example lán go maith luachanna a chóipeáil go sásta nach dteastaíonn uait le feiceáil i gcomhad leaganaithe.
Doiciméadú API
I gcás REST API, is é an doiciméadú is cost-éifeachtaí ná an ceann is féidir le huirlisí eile a úsáid gan idirghabháil dhaonna.
"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."
Baintear gach rud as an gcód: conairí bealaigh, modhanna HTTP, scéimrí bailíochtaithe, agus cineálacha freagartha. Dá bhrí sin, tá an tsainmhíniú a thagann as dílis don chur chun feidhme, rud a ligeann do do thomhaltóirí cliant típithe nó bailiúchán tástála a dhíorthú gan aon cheist a chur ort.
Doiciméadú Ailtireachta
Is annamh a scríobhtar cinntí ailtireachta síos. Nuair a dhéantar, déanann siad cur síos ar an rún tosaigh seachas ar an réaltacht trí bliana ina dhiaidh sin. Iarr ar Codex foirmiú a dhéanamh ar an méid atá ann i ndáiríre sa chód.
"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"
Tá sochar tánaisteach gan choinne ag an doiciméad seo: trí spleáchais mhodúil a chur síos mar atá siad i ndáiríre, nochtann sé cúplálacha nár admhaigh aon duine riamh—mar shampla, an seirbhís billiúcháin ag iompórtáil fóntais ón modúl fíordheimhniúcháin.
Doiciméadú Atá Ann Cheana a Nuashonrú
Tá doiciméadú as dáta níos measa ná gan doiciméadú ar bith toisc go gcuireann sé amú ama ort le húdarás.
"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."
Déanann Codex gach maíomh sa README a chur i gcomparáid leis an gcód iarbhír agus ceartaíonn sé neamhréireachtaí. Sceideal an tasc seo go tréimhsiúil, mar shampla roimh gach scaoileadh, seachas a fháil amach go bhfuil gá leis an lá a fhaigheann fostaithe nua nach n-oibríonn aon cheann de na horduithe suiteála.
Uathoibriú trí AGENTS.md
Chun stop a chur le doiciméadú a mheas mar chúram ar leith, déan srian buan den chuid den tionscadal é.
## 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
Leis na trí riail seo, iompraíonn gach tasc forbartha a nuashonrú doiciméadaithe féin. Stopann an bhearna idir an cód agus an cur síos ag leathnú go ciúin, rud arb é an t-aon bhealach inbhuanaithe chun an cath seo a bhuachan.
Príomhphointí
- Gineann Codex doiciméadú atá dílis don chód iarbhír, ní rud cumtha
- Is é an doiciméadú inlíne (JSDoc) an ceann is úsáidí don obair laethúil
- Is féidir le Codex READMEanna, sainmhínithe OpenAPI, agus doiciméadú ailtireachta a tháirgeadh
- Úsáid Codex chun doiciméadú as dáta a bhrath agus a cheartú
- Cuir rialacha doiciméadaithe le AGENTS.md chun an próiseas a uathoibriú