Πώς να τεκμηριώσετε κώδικα JavaScript χρησιμοποιώντας JSDoc

Η σωστή τεκμηρίωση κώδικα είναι μια σημαντική αλλά συχνά παραβλέπεται πτυχή της ανάπτυξης λογισμικού. Ως προγραμματιστής, θα έχετε συνηθίσει να γράφετε καθαρό, αποτελεσματικό κώδικα, αλλά μπορεί να είστε λιγότερο έμπειροι στη σύνταξη καλής τεκμηρίωσης.

Η καλή τεκμηρίωση είναι χρήσιμη για οποιονδήποτε εργάζεται με τον κώδικά σας, είτε πρόκειται για άλλα μέλη της ομάδας σας είτε για εσάς, τον εαυτό σας, σε μεταγενέστερη ημερομηνία. Μπορεί να εξηγήσει γιατί έχετε εφαρμόσει κάτι με συγκεκριμένο τρόπο ή πώς να χρησιμοποιήσετε μια συγκεκριμένη λειτουργία ή API.

Για προγραμματιστές JavaScript, το JSDoc είναι ένας καλός τρόπος για να ξεκινήσετε την τεκμηρίωση του κώδικά σας.

Τι είναι το JSDoc;

Η τεκμηρίωση του κώδικα μπορεί να είναι περίπλοκη και κουραστική. Ωστόσο, περισσότεροι άνθρωποι αναγνωρίζουν τα οφέλη του μια προσέγγιση «έγγραφα ως κώδικας».

Το JSDoc δημιουργεί τεκμηρίωση ερμηνεύοντας ειδικά σχόλια στον πηγαίο κώδικα JavaScript, επεξεργάζοντας αυτά τα σχόλια και δημιουργώντας ειδική τεκμηρίωση. Στη συνέχεια καθιστά αυτή την τεκμηρίωση διαθέσιμη σε προσβάσιμη μορφή HTML.

Αυτό διατηρεί την τεκμηρίωση εντός του κώδικα, επομένως όταν ενημερώνετε τον κωδικό σας, είναι εύκολο να ενημερώσετε την τεκμηρίωση.

Ρύθμιση του JSDoc

Οι δημιουργοί του JSDoc έχουν κάνει εύκολο να ξεκινήσετε και να ρυθμίσετε το JSDoc στο έργο σας JavaScript.

Για να εγκαταστήσετε το JSDoc τοπικά, εκτελέστε:

npm install --save-dev jsdoc

Αυτό θα εγκαταστήσει τη βιβλιοθήκη στο έργο σας ως εξάρτηση dev.

Για να χρησιμοποιήσετε το JSDoc, θα χρησιμοποιήσετε ειδικά συντακτικά σχόλια μέσα στον πηγαίο κώδικα. Θα γράψετε όλα τα σχόλια της τεκμηρίωσης μέσα /** και */ μαρκαδόροι. Μέσα σε αυτά, μπορείτε να περιγράψετε καθορισμένες μεταβλητές, συναρτήσεις, παραμέτρους συναρτήσεων και πολλά άλλα.

Για παράδειγμα:

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

ο @παραμ και @επιστρέφει Οι ετικέτες είναι δύο από τις πολλές ειδικές λέξεις-κλειδιά που υποστηρίζει το JSDoc για να εξηγήσει τον κώδικά σας.

Για να δημιουργήσετε την τεκμηρίωση για αυτόν τον κώδικα, εκτελέστε npx jsdoc ακολουθούμενη από τη διαδρομή προς το αρχείο JavaScript.

Για παράδειγμα:

npx jsdoc src/main.js

jsdoc path/to/file.js

Αυτή η εντολή θα δημιουργήσει ένα έξω φάκελο στη ρίζα του έργου σας. Μέσα στο φάκελο, θα βρείτε αρχεία HTML που αντιπροσωπεύουν τις σελίδες της τεκμηρίωσής σας.

Μπορείτε να δείτε την τεκμηρίωση από εγκατάσταση ενός τοπικού διακομιστή web για να τον φιλοξενήσει, ή απλά ανοίγοντας το αρχείο out/index.html μέσα σε ένα πρόγραμμα περιήγησης. Ακολουθεί ένα παράδειγμα για το πώς θα μοιάζει μια σελίδα τεκμηρίωσης από προεπιλογή:

Διαμόρφωση της εξόδου JSDoc

Μπορείτε να δημιουργήσετε ένα αρχείο διαμόρφωσης για να αλλάξετε την προεπιλεγμένη συμπεριφορά του JSDoc.

Για να το κάνετε αυτό, δημιουργήστε ένα conf.js αρχείο και εξαγωγή μιας λειτουργικής μονάδας JavaScript μέσα σε αυτό το αρχείο.

Για παράδειγμα:

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

Μέσα στο αρχείο ρυθμίσεων υπάρχουν διάφορα Διαμόρφωση JSDoc επιλογές. ο πρότυπο Η επιλογή σάς επιτρέπει να χρησιμοποιήσετε ένα πρότυπο για να προσαρμόσετε την εμφάνιση της τεκμηρίωσης. Η κοινότητα του JSDoc παρέχει πολλά πρότυπα που μπορείτε να χρησιμοποιήσετε. Το πακέτο σας επιτρέπει επίσης να δημιουργήσετε τα δικά σας εξατομικευμένα πρότυπα.

Για να αλλάξετε τη θέση της τεκμηρίωσης που δημιουργείται, ορίστε το προορισμός επιλογή config σε έναν κατάλογο. Το παραπάνω παράδειγμα προσδιορίζει α έγγραφα φάκελο στη ρίζα του έργου.

Χρησιμοποιήστε αυτήν την εντολή για να εκτελέσετε το JSDoc με ένα αρχείο διαμόρφωσης:

jsdoc -c /path/to/conf.js

Για να διευκολύνετε την εκτέλεση αυτής της εντολής, προσθέστε την ως α σενάρια είσοδος μέσα σου πακέτο.json αρχείο:

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

Μπορείς τώρα εκτελέστε την εντολή δέσμης ενεργειών npm μέσα σε ένα τερματικό.

Ένα παράδειγμα τεκμηρίωσης που δημιουργήθηκε με το JSDoc

Παρακάτω είναι μια απλή αριθμητική βιβλιοθήκη με Προσθήκη και αφαιρώ μεθόδους.

Αυτό είναι ένα παράδειγμα καλά τεκμηριωμένου κώδικα 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 ...
};

Τα σχόλια του JSDoc παρέχουν μια σαφή και περιεκτική περιγραφή της βιβλιοθήκης και των μεθόδων της, συμπεριλαμβανομένων:

• Περιγραφή της βιβλιοθήκης και του σκοπού της.
• Οι παράμετροι κάθε μεθόδου, συμπεριλαμβανομένου του τύπου τους και μιας σύντομης περιγραφής.
• Η τιμή και ο τύπος που επιστρέφει κάθε μέθοδος.
• Τα λάθη που μπορεί να πετάξει κάθε μέθοδος και οι συνθήκες που το προκαλούν.
• Ένα παράδειγμα για το πώς να χρησιμοποιήσετε κάθε μέθοδο.

Τα σχόλια περιλαμβάνουν επίσης το @μονάδα μέτρησης ετικέτα για να υποδείξετε ότι αυτό το αρχείο είναι μια ενότητα και το @παράδειγμα ετικέτα για να παρέχει ένα παράδειγμα κώδικα για κάθε μέθοδο.

Τεκμηρίωση του κώδικα προγραμματιστή με τον σωστό τρόπο

Όπως μπορείτε να δείτε, το JSDoc είναι ένα πολύ χρήσιμο εργαλείο για να ξεκινήσετε την τεκμηρίωση κώδικα JavaScript. Με την εύκολη ενσωμάτωσή του, μπορείτε να δημιουργήσετε γρήγορη και λεπτομερή τεκμηρίωση καθώς γράφετε τον κώδικά σας. Μπορείτε επίσης να διατηρήσετε και να ενημερώσετε την τεκμηρίωση απευθείας στον χώρο εργασίας σας.

Ωστόσο, όσο χρήσιμη και αν είναι η αυτοματοποίηση του JSDoc, θα πρέπει να τηρείτε ορισμένες οδηγίες, ώστε να μπορείτε να δημιουργήσετε ποιοτική τεκμηρίωση.