JavaScript-koodin dokumentointi JSDocilla

Asianmukainen koodidokumentaatio on tärkeä mutta usein unohdettu osa ohjelmistokehitystä. Kehittäjänä olet tottunut kirjoittamaan puhdasta ja tehokasta koodia, mutta saatat olla vähemmän kokenut hyvän dokumentaation kirjoittamisessa.

Hyvästä dokumentaatiosta on hyötyä kaikille, jotka työskentelevät koodisi parissa, olipa kyseessä muut tiimisi jäsenet tai sinä itse, myöhemmin. Se voi selittää, miksi olet toteuttanut jotain tietyllä tavalla tai kuinka käyttää tiettyä toimintoa tai API: ta.

JavaScript-kehittäjille JSDoc on hyvä tapa aloittaa koodin dokumentointi.

Mikä on JSDoc?

Koodin dokumentointi voi olla monimutkaista ja työlästä. Yhä useammat ihmiset kuitenkin tiedostavat sen hyödyt "dokumentit koodina" -lähestymistapa, ja monilla kielillä on kirjastoja, jotka auttavat automatisoimaan prosessin. Yksinkertainen, selkeä ja ytimekäs dokumentaatio. Aivan kuten

JSDoc luo dokumentaatiota tulkitsemalla erikoiskommentteja JavaScript-lähdekoodissasi, käsittelemällä nämä kommentit ja tuottamalla räätälöityjä asiakirjoja. Sen jälkeen tämä dokumentaatio on saatavilla HTML-muodossa.

Tämä pitää dokumentaation koodin sisällä, joten kun päivität koodin, dokumentaation päivittäminen on helppoa.

Asetetaan JSDoc

JSDocin luojat ovat tehneet helpoksi aloittamisen ja JSDocin määrittämisen JavaScript-projektissasi.

Asenna JSDoc paikallisesti suorittamalla:

npm install --save-dev jsdoc

Tämä asentaa kirjaston projektiisi kehittäjäriippuvuutena.

Jos haluat käyttää JSDocia, käytä lähdekoodissasi erityisiä syntaksikommentteja. Kirjoitat kaikki dokumentaatiokommenttisi sisään /** ja */ merkit. Näiden sisällä voit kuvata määriteltyjä muuttujia, toimintoja, funktioparametreja ja paljon muuta.

Esimerkiksi:

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

The @param ja @palauttaa tagit ovat kaksi monista erikoisavainsanoista, joita JSDoc tukee koodisi selittämiseksi.

Luo tämän koodin dokumentaatio suorittamalla npx jsdoc jota seuraa JavaScript-tiedostosi polku.

Esimerkiksi:

npx jsdoc src/main.js

jsdoc path/to/file.js

Tämä komento luo an ulos kansio projektisi juuressa. Kansion sisältä löydät HTML-tiedostoja, jotka edustavat dokumentaatiosi sivuja.

Voit tarkastella dokumentaatiota osoitteessa paikallisen verkkopalvelimen asettaminen isännöimään sitä, tai yksinkertaisesti avaamalla out/index.html-tiedosto selaimessa. Tässä on esimerkki siitä, miltä dokumentaatiosivu näyttää oletusarvoisesti:

JSDoc-lähdön määrittäminen

Voit luoda määritystiedoston muuttaaksesi JSDocin oletuskäyttäytymistä.

Luo tätä varten a conf.js tiedosto ja vie JavaScript-moduuli tämän tiedoston sisään.

Esimerkiksi:

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

Konfigurointitiedoston sisällä on erilaisia JSDoc-kokoonpano vaihtoehtoja. The sapluuna -vaihtoehdon avulla voit mukauttaa dokumentaation ulkoasua mallin avulla. JSDocin yhteisö tarjoaa monia malleja joita voit käyttää. Paketin avulla voit myös luoda omia yksilöllisiä malleja.

Jos haluat muuttaa luodun dokumentaation sijaintia, aseta määränpäähän config-vaihtoehto hakemistoon. Yllä oleva esimerkki määrittelee a asiakirjoja kansio projektin juuressa.

Käytä tätä komentoa suorittaaksesi JSDoc määritystiedoston kanssa:

jsdoc -c /path/to/conf.js

Tämän komennon suorittamisen helpottamiseksi lisää se muodossa a käsikirjoituksia sisäänkäynti sisälläsi package.json tiedosto:

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

Nyt voit suorita npm-skriptikomento terminaalin sisällä.

Esimerkki JSDocilla luodusta dokumentaatiosta

Alla on yksinkertainen aritmeettinen kirjasto lisätä ja vähentää menetelmiä.

Tämä on esimerkki hyvin dokumentoidusta JavaScript-koodista:

/**
 * 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-kommentit tarjoavat selkeän ja kattavan kuvauksen kirjastosta ja sen menetelmistä, mukaan lukien:

• Kuvaus kirjastosta ja sen tarkoituksesta.
• Kunkin menetelmän parametrit, mukaan lukien niiden tyyppi ja lyhyt kuvaus.
• Arvo ja tyyppi, jotka kukin menetelmä palauttaa.
• Virheet, joita kukin menetelmä voi aiheuttaa, ja olosuhteet, jotka aiheuttavat sen.
• Esimerkki kunkin menetelmän käytöstä.

Kommenteissa on myös mm @moduuli -tunniste osoittaa, että tämä tiedosto on moduuli ja @esimerkki -tunniste antaaksesi koodiesimerkin jokaiselle menetelmälle.

Dokumentoi kehittäjäkoodi oikealla tavalla

Kuten näet, JSDoc on erittäin hyödyllinen työkalu JavaScript-koodin dokumentoinnin aloittamiseen. Sen helpon integroinnin ansiosta voit luoda nopean ja yksityiskohtaisen dokumentaation kirjoittaessasi koodia. Voit myös ylläpitää ja päivittää dokumentaatiota suoraan työtilassasi.

Vaikka JSDocin automaatio onkin hyödyllistä, sinun tulee silti noudattaa tiettyjä ohjeita, jotta voit luoda laadukasta dokumentaatiota.