Kaip dokumentuoti JavaScript kodą naudojant JSDoc

Tinkama kodo dokumentacija yra svarbus, tačiau dažnai nepastebimas programinės įrangos kūrimo aspektas. Kaip kūrėjas būsite įpratę rašyti švarų ir efektyvų kodą, bet galbūt būsite mažiau patyrę rašydami gerą dokumentaciją.

Geri dokumentai yra naudingi visiems, dirbantiems su jūsų kodu, nesvarbu, ar tai būtų kiti jūsų komandos nariai, ar jūs patys, vėliau. Tai gali paaiškinti, kodėl ką nors įdiegėte tam tikru būdu arba kaip naudoti tam tikrą funkciją ar API.

„JavaScript“ kūrėjams JSDoc yra geras būdas pradėti dokumentuoti kodą.

Kas yra JSDoc?

Kodo dokumentavimas gali būti sudėtingas ir varginantis. Tačiau vis daugiau žmonių pripažįsta jo naudą „dokumentai kaip kodas“ metodas, ir daugelyje kalbų yra bibliotekų, kurios padeda automatizuoti procesą. Paprastam, aiškiam ir glaustam dokumentavimui. Visai kaip ir Go kalba turi GoDoc automatizuoti dokumentaciją iš kodo, todėl JavaScript turi JSDoc.

JSDoc generuoja dokumentus interpretuodama specialius komentarus jūsų „JavaScript“ šaltinio kode, apdorodama šiuos komentarus ir sudarydama pagal užsakymą pagamintą dokumentaciją. Tada ši dokumentacija bus prieinama prieinamu HTML formatu.

Taip dokumentai lieka kode, todėl atnaujinus kodą dokumentaciją atnaujinti bus lengva.

JSDoc nustatymas

JSDoc kūrėjai padėjo lengvai pradėti ir nustatyti JSDoc savo JavaScript projekte.

Norėdami įdiegti JSDoc vietoje, paleiskite:

npm install --save-dev jsdoc

Taip biblioteka bus įdiegta jūsų projekte kaip kūrėjo priklausomybė.

Norėdami naudoti JSDoc, šaltinio kode naudosite specialius sintaksės komentarus. Parašysite visus savo dokumento komentarus /** ir */ žymekliai. Juose galite aprašyti apibrėžtus kintamuosius, funkcijas, funkcijų parametrus ir daug kitų.

Pavyzdžiui:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

The @param ir @grįžta žymos yra du iš daugelio specialių raktinių žodžių, kuriuos palaiko JSDoc, kad paaiškintų jūsų kodą.

Norėdami sukurti šio kodo dokumentaciją, paleiskite npx jsdoc po kurio nurodomas kelias į „JavaScript“ failą.

Pavyzdžiui:

npx jsdoc src/main.js

jsdoc path/to/file.js

Ši komanda sugeneruos išeiti aplanką savo projekto šaknyje. Aplanko viduje rasite HTML failus, vaizduojančius jūsų dokumentacijos puslapius.

Dokumentaciją galite peržiūrėti per nustatyti vietinį žiniatinklio serverį, kad jį priglobtų, arba tiesiog naršyklėje atidarydami failą out/index.html. Štai pavyzdys, kaip pagal numatytuosius nustatymus atrodys dokumentacijos puslapis:

JSDoc išvesties konfigūravimas

Galite sukurti konfigūracijos failą, kad pakeistumėte numatytąjį JSDoc elgesį.

Norėdami tai padaryti, sukurkite a conf.js failą ir eksportuokite JavaScript modulį į šį failą.

Pavyzdžiui:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

Konfigūracijos failo viduje yra įvairių JSDoc konfigūracija galimybės. The šabloną parinktis leidžia naudoti šabloną dokumentacijos išvaizdai tinkinti. JSDoc bendruomenė teikia daug šablonus kuriuos galite naudoti. Paketas taip pat leidžia jums sukurti savo asmeninius šablonus.

Norėdami pakeisti sukurtos dokumentacijos vietą, nustatykite Kelionės tikslas config parinktis į katalogą. Aukščiau pateiktame pavyzdyje nurodyta a dok aplanką projekto šaknyje.

Naudokite šią komandą, kad paleistumėte JSDoc su konfigūracijos failu:

jsdoc -c /path/to/conf.js

Kad būtų lengviau vykdyti šią komandą, pridėkite ją kaip a scenarijus įėjimas jūsų viduje package.json failas:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Dabar galite paleiskite npm scenarijaus komandą terminalo viduje.

Dokumentacijos, sukurtos naudojant JSDoc, pavyzdys

Žemiau yra paprasta aritmetinė biblioteka su papildyti ir atimti metodus.

Tai yra gerai dokumentuoto „JavaScript“ kodo pavyzdys:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

JSDoc komentaruose pateikiamas aiškus ir išsamus bibliotekos ir jos metodų aprašymas, įskaitant:

• Bibliotekos aprašymas ir jos paskirtis.
• Kiekvieno metodo parametrai, įskaitant jų tipą ir trumpą aprašymą.
• Vertė ir tipas, kuriuos grąžina kiekvienas metodas.
• Klaidos, kurias gali sukelti kiekvienas metodas, ir ją sukeliančios sąlygos.
• Kiekvieno metodo naudojimo pavyzdys.

Komentaruose taip pat yra @modulis žyma, nurodanti, kad šis failas yra modulis ir @pavyzdys žymą, kad pateiktumėte kiekvieno metodo kodo pavyzdį.

Teisingas kūrėjo kodo dokumentavimas

Kaip matote, JSDoc yra labai naudingas įrankis, leidžiantis pradėti dokumentuoti JavaScript kodą. Lengvai integruodami galite greitai ir išsamiai sugeneruoti dokumentaciją, kai rašote kodą. Taip pat galite tvarkyti ir atnaujinti dokumentaciją tiesiog savo darbo vietoje.

Tačiau, kad ir kaip naudinga būtų JSDoc automatizavimas, vis tiek turėtumėte laikytis tam tikrų gairių, kad galėtumėte sukurti kokybišką dokumentaciją.