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.
Spis treści:
Co to jest JSDoc?
Dokumentowanie kodu może być złożone i żmudne. Jednak coraz więcej osób dostrzega zalety podejścia „dokumenty jako kod”, a wiele języków ma biblioteki, które pomagają zautomatyzować proces. Prosta, jasna i zwięzła dokumentacja. Tak jak język Go ma GoDoc do automatyzacji dokumentacji z kodu, tak JavaScript ma JSDoc.
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. Wszystkie komentarze do dokumentacji napiszesz w znacznikach /** i */. 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
*/function getUser(name) {
const User = name;
return User;
}
Tagi @param i @returns to dwa z wielu specjalnych słów kluczowych obsługiwanych przez JSDoc w celu wyjaśnienia kodu.
Aby wygenerować dokumentację tego kodu, uruchom npx jsdoc, a następnie podaj ścieżkę do pliku JavaScript.
Na przykład:
npx jsdoc src/main.js
Jeśli zainstalowałeś JSDoc globalnie, możesz pominąć flagę npx i uruchomić:
To polecenie wygeneruje folder wyjściowy w katalogu głównym projektu. Wewnątrz folderu znajdziesz pliki HTML reprezentujące strony Twojej dokumentacji.
Możesz przeglądać dokumentację, konfigurując lokalny serwer WWW do jej hostowania 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.
W tym celu utwórz plik conf.js i wyeksportuj wewnątrz tego pliku moduł JavaScript.
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. Opcja szablonu 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ę konfiguracji docelowej na katalog. Powyższy przykład określa folder dokumentów 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 wpis skryptu w pliku package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Możesz teraz uruchomić polecenie skryptu npm w terminalu.
Przykład dokumentacji wygenerowanej za pomocą JSDoc
Poniżej znajduje się prosta biblioteka arytmetyczna z metodami dodawania i odejmowania.
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);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('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);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
Komentarze JSDoc zapewniają jasny i kompleksowy opis biblioteki i jej metod, w tym:
- Opis biblioteki i jej przeznaczenia.
- Parametry każdej metody, w tym ich typ 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.
Komentarze zawierają także znacznik @module wskazujący, że ten plik jest modułem oraz znacznik @example dostarczający 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ę.