Jak dokumentować kod JavaScript za pomocą JSDoc
Właściwa dokumentacja kodu jest ważnym, ale często pomijanym aspektem tworzenia oprogramowania. Jako programista będziesz przyzwyczajony do pisania czystego, wydajnego kodu, ale możesz być mniej doświadczony w pisaniu dobrej dokumentacji.
Skuteczna dokumentacja służy jako nieocenione źródło informacji dla wszystkich osób zaangażowanych we współpracę obejmującą bazę kodu, w tym obecne i przyszłe iteracje samego siebie. Zapewniając wyjaśnienie wyborów projektowych i oferując wskazówki dotyczące korzystania z określonych funkcji lub interfejsów API, sprzyja lepszemu zrozumieniu i wydajności wśród użytkowników.
Dla tych, którzy są biegli w programowaniu JavaScript, wykorzystanie JSDoc stanowi doskonały sposób na rozpoczęcie procesu tworzenia dokumentacji dla ich bazy kodu.
Czym jest JSDoc?
Przyjęcie strategii “docs-as-code” staje się coraz bardziej popularne, a wiele języków programowania zapewnia dedykowane biblioteki usprawniające ten proces. Narzędzia te umożliwiają programistom generowanie kompleksowej, ale zwięzłej dokumentacji bez wysiłku. Dla przykładu, język programowania Go oferuje GoDoc do automatycznego generowania dokumentacji na podstawie adnotacji kodu, podczas gdy JavaScript opiera się na JSDoc do podobnych celów w swoim ekosystemie.
Wykorzystując specjalne komentarze osadzone w kodzie źródłowym JavaScript, JSDoc skutecznie wyodrębnia i przetwarza takie adnotacje w celu wygenerowania dostosowanej dokumentacji. Dokumentacja ta jest następnie formatowana do przyjaznego dla użytkownika formatu HTML w celu zapewnienia wygodnego dostępu.
Integrując dokumentację bezpośrednio z kodem źródłowym, podejście to ułatwia płynny proces aktualizacji zarówno kodu, jak i odpowiadającej mu dokumentacji za każdym razem, gdy wprowadzane są modyfikacje w tym pierwszym.
Konfigurowanie JSDoc
Projektanci JSDoc uprościli proces inicjowania i integracji JSDoc w projekcie JavaScript, czyniąc go dostępnym i przyjaznym dla użytkownika od samego początku.
Aby zainstalować JSDoc lokalnie, uruchom:
npm install --save-dev jsdoc
Zainstalowanie biblioteki jako zależności rozwojowej w projekcie pociąga za sobą włączenie jej do istniejącej infrastruktury projektu, umożliwiając wykorzystanie jej funkcji i funkcjonalności w razie potrzeby.
Jak pisać komentarze JSDoc
Aby korzystać z JSDoc, należy włączyć określoną składnię komentarzy bezpośrednio w kodzie źródłowym.Wszystkie uwagi dotyczące dokumentacji należy umieścić w znacznikach / i */ / , które umożliwiają szczegółowe opisanie szerokiej gamy elementów, takich jak zdefiniowane zmienne, funkcje, parametry funkcji i różne inne istotne informacje.
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;
}
JSDoc to narzędzie dokumentacji dla JavaScript, które wykorzystuje różne specjalistyczne słowa kluczowe, w tym “@param” i “@returns”, aby zapewnić przejrzystość kodu. Te konkretne słowa kluczowe służą jako adnotacje odpowiednio dla parametrów funkcji i wartości zwracanych, pozwalając programistom lepiej zrozumieć, w jaki sposób ich kod powinien być używany i jakich wyników można się po nim spodziewać.
Aby utworzyć kompleksowy dokument opisujący funkcjonalność tego skryptu, wykonaj polecenie “npx jsdoc”, a następnie określoną ścieżkę prowadzącą do pliku JavaScript.
Na przykład:
npx jsdoc src/main.js
Jeśli zainstalowałeś JSDoc jako pakiet globalny, możesz zrezygnować z użycia polecenia “npx”, po prostu wykonując:
jsdoc path/to/file.js
Wykonanie tej instrukcji spowoduje utworzenie katalogu o nazwie “out” w katalogu głównym twojego projektu. We wspomnianym katalogu znajdują się dokumenty HTML, które zawierają zawartość dokumentacji.
Aby uzyskać dostęp do dokumentacji, dostępne są dwie opcje. Pierwsza polega na skonfigurowaniu lokalnego serwera WWW, który będzie służył jako platforma hostingowa dla plików dokumentacji. Alternatywnie można otworzyć zawartość pliku out/index.html w preferowanej przeglądarce internetowej, aby bezpośrednio wyświetlić dokumentację. Należy pamiętać, że domyślny wygląd strony dokumentacji jest następujący:
Konfigurowanie wyjścia JSDoc
Istnieje możliwość wykorzystania niestandardowego pliku konfiguracyjnego do modyfikacji standardowej funkcjonalności JSDoc.
Aby osiągnąć ten cel, konieczne jest utworzenie pliku konfiguracyjnego o nazwie “conf.js”. W tym pliku należy wyeksportować moduł JavaScript, który będzie służył zamierzonemu celowi.
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 znajdują się różne opcje konfiguracji JSDoc . Opcja szablonu umożliwia użycie szablonu w celu dostosowania wyglądu dokumentacji. Społeczność JSDoc dostarcza wiele szablonów , których można użyć. Pakiet umożliwia również tworzenie własnych spersonalizowanych szablonów.
Aby przenieść automatycznie utworzoną dokumentację, należy wyznaczyć określony katalog jako miejsce docelowe, dostosowując ustawienie konfiguracji oznaczone jako “miejsce docelowe”. Jak wykazano wcześniej, określenie wyznaczonego folderu “docs” znajdującego się w głównym obszarze przechowywania projektu skutecznie osiągnie ten cel.
Wykonaj następującą dyrektywę, aby obsługiwać JSDoc przy użyciu pliku konfiguracyjnego:
jsdoc -c /path/to/conf.js
Aby uprościć wykonywanie tego polecenia, dołącz je jako wpis “scripts” w pliku “package.json”. Pozwoli to na wygodne wykonanie polecenia z dowolnego miejsca w katalogu projektu poprzez uruchomienie “npm run [nazwa skryptu]”.
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Można teraz wykonać polecenie npm script w środowisku terminala, umożliwiając wykonanie predefiniowanych poleceń skryptowych powiązanych z Menedżerem pakietów Node.
Przykład dokumentacji wygenerowanej za pomocą JSDoc
Poniżej znajduje się elementarna biblioteka arytmetyczna zawierająca metody dodawania i odejmowania.
Ten przykład demonstruje zwięzłą i dobrze zorganizowaną implementację JavaScript, charakteryzującą się przejrzystą dokumentacją, która ułatwia zrozumienie i utrzymanie.
/**
* 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') {
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); // 5
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}
return a - b;
}
// ... other methods ...
};
Komentarze JSDoc oferują dogłębny i wszechstronny opis biblioteki i jej funkcjonalności, które obejmują:
Biblioteka służy jako repozytorium różnych dzieł literackich, zapewniając klientom obszerną kolekcję książek, które zaspokajają ich intelektualne poszukiwania. Jej głównym celem jest ułatwienie dostępu do informacji i wiedzy, umożliwiając jednostkom poszerzanie horyzontów poprzez czytanie i uczenie się. Biblioteka odgrywa również istotną rolę w zachowaniu dziedzictwa kulturowego poprzez utrzymywanie archiwów dokumentów historycznych i skarbów literackich.
Zmienne wejściowe każdej metody, w tym ich typ danych i zwięzłe wyjaśnienie.
Charakterystyka, znaczenie lub charakter danych wyjściowych generowanych przez każdą funkcję może różnić się pod względem wartości i klasyfikacji.
Aby lepiej zrozumieć potencjalne kwestie związane z daną metodą, ważne jest, aby wziąć pod uwagę zarówno rodzaje błędów, które mogą być generowane przez metodę, jak również wszelkie szczególne warunki lub okoliczności, w których błędy te są bardziej prawdopodobne. Zdając sobie sprawę z tych czynników, programiści mogą podjąć kroki w celu ograniczenia ryzyka i zapewnienia, że ich kod działa płynnie w różnych sytuacjach.
Komentarze w podanym kodzie zawierają dwa ważne znaczniki, a mianowicie znacznik “@module” i znacznik “@example”.Pierwszy z nich wskazuje, że plik jest modułem, podczas gdy drugi zawiera przykładowy kod dla każdej odpowiedniej metody. Znaczniki te służą jako przydatne odniesienia dla programistów, którzy szukają wskazówek, jak skutecznie wykorzystać te metody w swoich własnych projektach.
Dokumentowanie kodu programisty we właściwy sposób
Rzeczywiście, JSDoc służy jako skuteczny środek do generowania kompleksowej dokumentacji kodu JavaScript poprzez płynne włączenie go do procesu programowania. Ułatwia to szybkie generowanie zarówno zwięzłej, jak i skomplikowanej dokumentacji, jednocześnie umożliwiając ciągłe aktualizacje i poprawki w środowisku projektu.
Chociaż automatyzacja zapewniana przez JSDoc może być bardzo pomocna w generowaniu dokumentacji, to jednak konieczne jest przestrzeganie pewnych wytycznych i najlepszych praktyk w celu zapewnienia tworzenia wysokiej jakości dokumentacji.