Správná dokumentace programového kódu je klíčová, nicméně často opomíjená součást vývoje softwaru. Jako programátoři se soustředíte na psaní čistého a funkčního kódu, ale tvorba kvalitní dokumentace může být pro vás méně známou oblastí.
Dobře napsaná dokumentace je neocenitelná pro všechny, kdo pracují s vaším kódem, ať už jde o kolegy z týmu, nebo o vás v budoucnu. Může objasnit, proč jste zvolili určité řešení, nebo jak používat konkrétní funkci či API.
Pro vývojáře v JavaScriptu je JSDoc výborným nástrojem pro zahájení dokumentování kódu.
Co je JSDoc?
Dokumentování kódu může být zdlouhavé a náročné. Nicméně, stále více vývojářů chápe výhody přístupu „dokumentace jako kód“ a mnoho programovacích jazyků nabízí knihovny pro automatizaci tohoto procesu. Pro vytváření jednoduché, srozumitelné a stručné dokumentace existují nástroje, jako je GoDoc v jazyce Go nebo právě JSDoc v JavaScriptu.
JSDoc generuje dokumentaci na základě speciálních komentářů v JavaScriptovém kódu. Tyto komentáře analyzuje a transformuje do užitečné dokumentace, která je následně zpřístupněna v HTML formátu.
Díky tomuto přístupu je dokumentace přímo součástí kódu, a když kód upravujete, je snadné aktualizovat i jeho dokumentaci.
Nastavení JSDoc
Tvůrci JSDocu usnadnili jeho zprovoznění a nastavení ve vašem JavaScriptovém projektu.
Pro lokální instalaci JSDocu použijte příkaz:
npm install --save-dev jsdoc
Tím se knihovna nainstaluje do vašeho projektu jako vývojová závislost.
JSDoc používá speciální komentáře s konkrétní syntaxí. Všechny poznámky k dokumentaci se zapisují do bloků ohraničených značkami /** a */. V těchto blocích můžete popisovat definované proměnné, funkce, parametry funkcí a mnoho dalšího.
Například:
* Získá uživatele podle jména.
* @param {string} name - Jméno uživatele
* @returns {string} Uživatel
*/
function getUser(name) {
const User = name;
return User;
}
Značky @param a @returns jsou jen dvě z mnoha klíčových slov, které JSDoc využívá pro popis vašeho kódu.
Pro vygenerování dokumentace z tohoto kódu použijte příkaz npx jsdoc následovaný cestou k vašemu JavaScriptovému souboru.
Například:
npx jsdoc src/main.js
Pokud máte JSDoc nainstalovaný globálně, můžete vynechat prefix npx a spustit:
Tento příkaz vytvoří výstupní složku v kořenovém adresáři vašeho projektu. Uvnitř najdete HTML soubory, které tvoří stránky s vaší dokumentací.
Dokumentaci si můžete zobrazit spuštěním lokálního webového serveru nebo jednoduše otevřením souboru out/index.html ve webovém prohlížeči. Níže je příklad, jak bude dokumentace vypadat ve výchozím nastavení:
Konfigurace výstupu JSDoc
Chcete-li změnit výchozí nastavení JSDocu, můžete vytvořit konfigurační soubor.
Vytvořte soubor s názvem conf.js a do něj exportujte JavaScriptový modul.
Například:
module.exports = {
source: {
includePattern: ".+\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
V konfiguračním souboru najdete různé možnosti nastavení JSDoc. Volba šablony umožňuje změnit vzhled dokumentace. Komunita JSDoc nabízí množství šablon, které můžete použít. Je možné i vytvořit vlastní šablony.
Pro změnu umístění vygenerované dokumentace použijte volbu destination a nastavte cestu k požadovanému adresáři. V uvedeném příkladu je dokumentace generována do složky docs v kořenovém adresáři projektu.
Pro spuštění JSDoc s konfiguračním souborem použijte tento příkaz:
jsdoc -c /path/to/conf.js
Pro usnadnění spouštění tohoto příkazu, přidejte ho jako položku do skriptů v souboru package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Nyní můžete spustit příkaz npm script v terminálu.
Příklad dokumentace vygenerované pomocí JSDoc
Následuje příklad jednoduché aritmetické knihovny s funkcemi pro sčítání a odčítání.
Toto je ukázka dobře zdokumentovaného JavaScriptového kódu:
* Knihovna pro základní aritmetické operace.
* @module arithmetic
*/
module.exports = {
* Sečte dvě čísla.
* @param {number} a - První číslo.
* @param {number} b - Druhé číslo.
* @return {number} Součet dvou čísel.
* @throws {TypeError} Pokud některý z argumentů není číslo.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Oba argumenty musí být čísla.');
}
return a + b;
},
* Odečte druhé číslo od prvního.
* @param {number} a - Číslo, od kterého se odečítá.
* @param {number} b - Číslo, které se odečítá.
* @return {number} Výsledek odčítání.
* @throws {TypeError} Pokud některý z argumentů není číslo.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Oba argumenty musí být čísla.');
}
return a - b;
}
};
Komentáře JSDoc poskytují jasný a podrobný popis knihovny a jejích metod, včetně:
- Popisu knihovny a jejího účelu.
- Parametrů každé metody, včetně jejich typu a krátkého popisu.
- Hodnoty a typu, které každá metoda vrací.
- Chyb, které může každá metoda vyvolat, a podmínek, které je způsobují.
- Příkladu použití jednotlivých metod.
Komentáře také obsahují značku @module, která označuje, že se jedná o modul, a značku @example s příkladem použití každé metody.
Správný způsob dokumentování kódu
Jak vidíte, JSDoc je užitečný nástroj, který vám pomůže začít s dokumentováním kódu v JavaScriptu. Díky snadné integraci můžete vytvářet rychlou a detailní dokumentaci přímo při psaní kódu. Můžete ji také udržovat a aktualizovat přímo v rámci vašeho vývojového prostředí.
Nicméně, i když je automatizace s JSDoc užitečná, měli byste dodržovat určité zásady pro tvorbu kvalitní dokumentace.