Jak udokumentować kod JavaScript za pomocą JSDoc

Właściwa dokumentacja kodu jest ważnym, choć często pomijanym aspektem tworzenia oprogramowania. Jako programista będziesz przyzwyczajony do pisania czystego i wydajnego kodu, ale możesz mieć mniej doświadczenia w pisaniu dobrej dokumentacji.

Dobra dokumentacja jest przydatna dla każdego, kto pracuje z Twoim kodem, niezależnie od tego, czy są to inni członkowie Twojego zespołu, czy Ty sam w późniejszym terminie. Może wyjaśnić, dlaczego zaimplementowałeś coś w określony sposób lub jak korzystać z określonej funkcji lub interfejsu API.

Dla programistów JavaScript JSDoc to dobry sposób na rozpoczęcie dokumentowania kodu.

Co to jest JSDoc?

Dokumentowanie kodu może być złożone i żmudne. Jednak coraz więcej osób dostrzega zalety podejście „dokumenty jako kod”., a wiele języków ma biblioteki, które pomagają zautomatyzować proces. Prosta, jasna i zwięzła dokumentacja. Podobnie jak

JSDoc generuje dokumentację poprzez interpretację specjalnych komentarzy w kodzie źródłowym JavaScript, przetwarzanie tych komentarzy i tworzenie dokumentacji na zamówienie. Następnie udostępnia tę dokumentację w przystępnym formacie HTML.

Dzięki temu dokumentacja znajduje się w kodzie, więc po zaktualizowaniu kodu łatwo jest zaktualizować dokumentację.

Konfigurowanie JSDoc

Twórcy JSDoc ułatwili rozpoczęcie i konfigurację JSDoc w projekcie JavaScript.

Aby zainstalować JSDoc lokalnie, uruchom:

npm install --save-dev jsdoc

Spowoduje to zainstalowanie biblioteki w projekcie jako zależność deweloperską.

Aby używać JSDoc, użyjesz specjalnych komentarzy składniowych w kodzie źródłowym. W nim napiszesz wszystkie swoje komentarze do dokumentacji /** I */ znaczniki. Można w nich opisać zdefiniowane zmienne, funkcje, parametry funkcji i wiele więcej.

Na przykład:

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

The @param I @zwroty tagi to dwa z wielu specjalnych słów kluczowych obsługiwanych przez JSDoc w celu wyjaśnienia kodu.

Aby wygenerować dokumentację dla tego kodu, uruchom npx jsdoc po którym następuje ścieżka do pliku JavaScript.

Na przykład:

npx jsdoc src/main.js

jsdoc path/to/file.js

To polecenie wygeneruje plik na zewnątrz folder w katalogu głównym projektu. Wewnątrz folderu znajdziesz pliki HTML reprezentujące strony Twojej dokumentacji.

Dokumentację możesz przeglądać poprzez skonfiguruj lokalny serwer WWW, który będzie go hostowałlub po prostu otwierając plik out/index.html w przeglądarce. Oto przykład domyślnego wyglądu strony dokumentacji:

Konfigurowanie wyjścia JSDoc

Możesz utworzyć plik konfiguracyjny, aby zmienić domyślne zachowanie JSDoc.

Aby to zrobić, utwórz plik konf.js plik i wyeksportuj moduł JavaScript wewnątrz tego pliku.

Na przykład:

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

Wewnątrz pliku konfiguracyjnego są różne Konfiguracja JSDoc opcje. The szablon Opcja umożliwia użycie szablonu w celu dostosowania wyglądu dokumentacji. Społeczność JSDoc zapewnia wiele szablony z którego możesz skorzystać. Pakiet umożliwia także tworzenie własnych spersonalizowanych szablonów.

Aby zmienić lokalizację wygenerowanej dokumentacji, ustaw opcję miejsce docelowe config do katalogu. Powyższy przykład określa a dokumenty folder w katalogu głównym projektu.

Użyj tego polecenia, aby uruchomić JSDoc z plikiem konfiguracyjnym:

jsdoc -c /path/to/conf.js

Aby ułatwić uruchomienie tego polecenia, dodaj je jako skrypty wejście do twojego pakiet.json plik:

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

Możesz teraz uruchom polecenie skryptu npm wewnątrz terminala.

Przykład dokumentacji wygenerowanej za pomocą JSDoc

Poniżej znajduje się prosta biblioteka arytmetyczna z dodać I odejmować metody.

Oto przykład dobrze udokumentowanego kodu JavaScript:

/**
 * 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 ...
};

Komentarze JSDoc zawierają jasny i kompleksowy opis biblioteki i jej metod, w tym:

• Opis biblioteki i jej przeznaczenia.
• Parametry każdej metody, w tym ich rodzaj i krótki opis.
• Wartość i typ zwracany przez każdą metodę.
• Błędy, które może zgłosić każda metoda, oraz warunki, które je powodują.
• Przykład użycia każdej metody.

W komentarzach pojawia się także tzw @moduł znacznik wskazujący, że ten plik jest modułem, a plik @przykład tag, aby podać przykładowy kod dla każdej metody.

Dokumentowanie kodu programisty we właściwy sposób

Jak widać, JSDoc jest bardzo przydatnym narzędziem ułatwiającym rozpoczęcie dokumentowania kodu JavaScript. Dzięki łatwej integracji możesz szybko generować szczegółową dokumentację podczas pisania kodu. Możesz także zarządzać i aktualizować dokumentację bezpośrednio w swoim obszarze roboczym.

Jednak niezależnie od tego, jak przydatna jest automatyzacja JSDoc, nadal powinieneś przestrzegać pewnych wytycznych, aby móc tworzyć wysokiej jakości dokumentację.