Referenčna dokumentacija
Referenčna dokumentacija podaja podrobnosti o programskih elementih (knjižnicah razredov, objektnih modelih, konstruktih jezika). Doslednost je ključna: standardna zasnova članka, predvidljivi naslovi in dosledno besedišče razvijalcem pomagajo hitro najti iskano.
Opomba: samodejno generirana vsebina (konfiguracijske sheme, možnosti prevajalnika, sporočila o napakah) morda ne sledi tem smernicam.
Naslovi člankov
Uporabite ime elementa, ki mu sledi vrsta (razred, metoda, lastnost, dogodek). Če si ime deli več elementov, dodajte razločevalec (ime nadrejenega elementa ali tehnologije) – pomemben je zlasti v rezultatih iskanja.
Primeri: metoda Clear / metoda Device.Clear / metoda Clear (ADO)
Elementi referenčnega članka
| Razdelek | Vsebuje |
|---|---|
| Naslov in opis | ime elementa in jedrnat opis (en–dva stavka), kaj počne – brez ponavljanja imena. |
| Deklaracija/skladnja | signaturo, ki definira element; pri več jezikih skladnjo za vsakega. |
| Parametri | opis vsakega parametra in tipa; ali je obvezen ali neobvezen, vhodni ali izhodni. |
| Vrnjena vrednost | opis vrnjene vrednosti in tipa; pri logični vrednosti opišite pogoj. |
| Opombe | dodatne podrobnosti, ki niso očitne iz skladnje – pasti, primerjave, delovanje. |
| Primer | primer kode (glej Primeri kode). |
| Zahteve / velja za | jezikovne ali platformske zahteve. |
| Izjeme / kode napak | izjeme, ki jih element sproži, in pogoji zanje. |
| Pravice | varnostne pravice, kadar so potrebne. |
| Glej tudi | povezave na sorodne elemente in dodatne informacije. |
Pri samodejno generirani dokumentaciji iz komentarjev v kodi preglejte kakovost komentarjev in odstranite interne podrobnosti implementacije, neprimerne za dokumentacijo.
The White Knight Labs – Slovenski slogovni priročnik · avtor: Wolfgang van der Stille
Vsebina je izvirno napisana za slovenščino po Slovenskem pravopisu, SSKJ in Fran. Za zgradbo (razdelitev na razdelke) je vzet zgled dela Microsoft Writing Style Guide (© Microsoft Corporation, CC BY 4.0). Ta priročnik ni Microsoftov dokument in ni povezan z Microsoftom.