Kā dokumentēt JavaScript kodu, izmantojot JSDoc

Pareiza koda dokumentācija ir svarīgs, taču bieži vien aizmirsts programmatūras izstrādes aspekts. Kā izstrādātājs jūs būsiet pieradis rakstīt tīru, efektīvu kodu, taču jums var būt mazāka pieredze labas dokumentācijas rakstīšanā.

Laba dokumentācija ir noderīga ikvienam, kas strādā ar jūsu kodu, neatkarīgi no tā, vai tie ir citi jūsu komandas locekļi vai jūs pats vēlāk. Tas var izskaidrot, kāpēc esat kaut ko ieviesis noteiktā veidā vai kā izmantot noteiktu funkciju vai API.

JavaScript izstrādātājiem JSDoc ir labs veids, kā sākt dokumentēt savu kodu.

Kas ir JSDoc?

Koda dokumentēšana var būt sarežģīta un nogurdinoša. Tomēr arvien vairāk cilvēku atzīst priekšrocības pieeja “dokumenti kā kods”., un daudzās valodās ir bibliotēkas, kas palīdz automatizēt procesu. Vienkāršai, skaidrai un kodolīgai dokumentācijai. Tāpat kā Go valodai ir GoDoc lai automatizētu dokumentāciju no koda, tāpēc JavaScript ir JSDoc.

JSDoc ģenerē dokumentāciju, interpretējot īpašos komentārus jūsu JavaScript avota kodā, apstrādājot šos komentārus un sagatavojot īpaši pielāgotu dokumentāciju. Pēc tam šī dokumentācija ir pieejama pieejamā HTML formātā.

Tādējādi dokumentācija tiek saglabāta kodā, tāpēc, atjauninot kodu, dokumentāciju ir viegli atjaunināt.

JSDoc iestatīšana

JSDoc veidotāji ir atvieglojuši darba sākšanu un JSDoc iestatīšanu jūsu JavaScript projektā.

Lai lokāli instalētu JSDoc, palaidiet:

npm install --save-dev jsdoc

Tādējādi bibliotēka jūsu projektā tiks instalēta kā izstrādātāja atkarība.

Lai izmantotu JSDoc, avota kodā izmantosiet īpašus sintakses komentārus. Jūs ierakstīsit visus savus dokumentācijas komentārus /** un */ marķieri. Tajās varat aprakstīt definētus mainīgos, funkcijas, funkciju parametrus un daudz ko citu.

Piemēram:

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

The @param un @atgriežas tagi ir divi no daudzajiem īpašajiem atslēgvārdiem, ko JSDoc atbalsta, lai izskaidrotu jūsu kodu.

Lai ģenerētu šī koda dokumentāciju, palaidiet npx jsdoc seko ceļš uz jūsu JavaScript failu.

Piemēram:

npx jsdoc src/main.js

jsdoc path/to/file.js

Šī komanda ģenerēs ārā mapi jūsu projekta saknē. Mapē atradīsit HTML failus, kas atspoguļo jūsu dokumentācijas lapas.

Jūs varat apskatīt dokumentāciju, izmantojot vietējā tīmekļa servera iestatīšana tā mitināšanai, vai vienkārši pārlūkprogrammā atverot failu out/index.html. Tālāk ir sniegts piemērs tam, kā pēc noklusējuma izskatīsies dokumentācijas lapa.

JSDoc izvades konfigurēšana

Varat izveidot konfigurācijas failu, lai mainītu JSDoc noklusējuma darbību.

Lai to izdarītu, izveidojiet a conf.js failu un eksportējiet JavaScript moduli šajā failā.

Piemēram:

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

Konfigurācijas faila iekšpusē ir dažādi JSDoc konfigurācija iespējas. The veidne opcija ļauj izmantot veidni, lai pielāgotu dokumentācijas izskatu. JSDoc kopiena piedāvā daudzas veidnes ko varat izmantot. Pakete arī ļauj jums izveidot savas personalizētās veidnes.

Lai mainītu ģenerētās dokumentācijas atrašanās vietu, iestatiet galamērķis konfigurācijas opcija direktorijā. Iepriekš minētajā piemērā ir norādīts a dok mapi projekta saknē.

Izmantojiet šo komandu, lai palaistu JSDoc ar konfigurācijas failu:

jsdoc -c /path/to/conf.js

Lai atvieglotu šīs komandas izpildi, pievienojiet to kā a skripti ieeja jūsu iekšienē pack.json fails:

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

Tagad varat palaidiet npm skripta komandu termināļa iekšpusē.

Ar JSDoc ģenerētas dokumentācijas piemērs

Zemāk ir vienkārša aritmētiskā bibliotēka ar pievienot un atņemt metodes.

Šis ir labi dokumentēta JavaScript koda piemērs:

/**
 * 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 komentāri sniedz skaidru un visaptverošu bibliotēkas un tās metožu aprakstu, tostarp:

• Bibliotēkas apraksts un tās mērķis.
• Katras metodes parametri, tostarp to veids un īss apraksts.
• Vērtība un veids, ko atgriež katra metode.
• Kļūdas, ko var radīt katra metode, un apstākļi, kas to izraisa.
• Katras metodes izmantošanas piemērs.

Komentāros ietilpst arī @modulis tagu, lai norādītu, ka šis fails ir modulis, un @piemērs tagu, lai katrai metodei sniegtu koda piemēru.

Pareiza izstrādātāja koda dokumentēšana

Kā redzat, JSDoc ir ļoti noderīgs rīks, lai palīdzētu jums sākt dokumentēt JavaScript kodu. Pateicoties vienkāršai integrācijai, koda rakstīšanas laikā varat izveidot ātru un detalizētu dokumentāciju. Varat arī uzturēt un atjaunināt dokumentāciju tieši savā darbvietā.

Tomēr, lai cik noderīga ir JSDoc automatizācija, jums joprojām ir jāievēro noteiktas vadlīnijas, lai varētu izveidot kvalitatīvu dokumentāciju.