Προσθήκη μεταδεδομένων στην τεκμηρίωσή σας
Η παροχή καλής τεκμηρίωσης είναι ένα βασικό καθήκον για κάθε προγραμματιστή. Όχι μόνο βοηθά τους συμμαθητές σας να κατανοήσουν γρήγορα τη συλλογιστική και ίσως τη διαδικασία σκέψης σας, αλλά σας βοηθά επίσης να μπείτε στον κώδικα πιο γρήγορα σε περίπτωση που επιστρέψετε σε αυτόν μετά από μερικούς μήνες.
Ως εκ τούτου, σκέφτηκα να δημιουργήσω μια (ημιτελή) λίστα ειδικών ετικετών για χρήση με σχόλια JSDoc. Αυτά είναι αυτά που προσωπικά χρησιμοποιώ πιο συχνά και που έχουν αποδειχθεί ότι παρέχουν πραγματικό όφελος.
Μια βασική αρχή
Το ακόλουθο παράδειγμα κώδικα δείχνει ένα απλό, βασικό παράδειγμα που πρέπει να χρησιμοποιείται για κάθε τεκμηρίωση. Σημειώνει το σκοπό, τις παραμέτρους καθώς και τον τύπο επιστροφής.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Παράδειγμα κώδικα στην τεκμηρίωση
Μπορείτε να παρέχετε ένα πραγματικό παράδειγμα ενσωματωμένου κώδικα με την ετικέτα "@example" για να κάνετε ορισμένες περιπτώσεις χρήσης πιο σαφείς. Αυτή η ετικέτα μπορεί επίσης να χρησιμοποιηθεί για γρήγορη εμφάνιση πιθανών περιπτώσεων ακμών σε πραγματικό σενάριο.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Μέλος ποιας ενότητας
Χρησιμοποιήστε την ετικέτα "@memberOf" για να ορίσετε ποια λειτουργική μονάδα ή γονική μεταβλητή φιλοξενεί τον τεκμηριωμένο κώδικα.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Σχολιασμός συνδέσμου
Μπορείτε να χρησιμοποιήσετε την ετικέτα "@see" μαζί με την ετικέτα "@link" για να παράσχετε μια σωστά μορφοποιημένη τεκμηρίωση URL, αντί να επικολλήσετε ορισμένες διευθύνσεις URL στην κύρια τεκμηρίωση.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Τεκμηρίωση γενικού τύπου
Εάν ο κώδικάς σας χρησιμοποιεί γενικούς τύπους, μπορείτε να χρησιμοποιήσετε την ετικέτα "@template" για να ορίσετε το όνομα γενικού τύπου. Αυτό το όνομα χρησιμοποιείται στη συνέχεια στις κοινές ετικέτες "@param" ως αναφορά τύπου.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Καθορισμός του συγγραφέα ενός κομματιού κώδικα
Σε ορισμένες περιπτώσεις, είναι σημαντικό να σχολιάσετε και τον συγγραφέα. Αυτό μπορεί απλά να επιτευχθεί με την ετικέτα "@author". Μπορείτε όχι μόνο να δώσετε το όνομά σας, αλλά και ένα email ως αναφορά επικοινωνίας.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Καταργημένος κωδικός
Δεν υπάρχουν πολλά να πούμε για την ετικέτα "@deprecated", καθώς κάνει ακριβώς αυτό που θα περιμένατε. Αυτή η ετικέτα χρησιμοποιείται συνήθως σε API και μπορεί επίσης να αναφέρεται στον νέο κώδικα.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Εκδοχή
Χρησιμοποιήστε την ετικέτα "@version" για να τεκμηριώσετε μια έκδοση για τον συγκεκριμένο κώδικα. Σημειώστε ότι αυτή η ετικέτα δεν αναφέρεται στην έκδοση της εφαρμογής, αλλά στην πραγματικότητα τη δική της. Μια αύξηση αυτής της έκδοσης σημαίνει ότι αυτός ο συγκεκριμένος κωδικός έχει αλλάξει.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Από τότε που ο κωδικός είναι διαθέσιμος για χρήση
Μπορείτε να χρησιμοποιήσετε την ετικέτα "@since" για να τεκμηριώσετε από ποιον αριθμό έκδοσης έχει προστεθεί ο ακόλουθος κώδικας στο δημόσιο API. Σημαντικό να σημειωθεί εδώ είναι ότι η έκδοση τώρα αναφέρεται στο πεδίο εφαρμογής. Αυτό έρχεται σε αντίθεση με την ετικέτα "@version" από πριν, η οποία έχει πεδίο εφαρμογής στο συγκεκριμένο μπλοκ κώδικα που εγγράφει.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
