Διαχείριση προσδιοριστικού Javadoc @since

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

Σημείωση: Οι πληροφορίες του προσδιοριστικού @since δεν κληροδοτούνται κατά την υλοποίησης ή τη δημιουργία υποκλάσεων. Θεωρείται δεδομένο ότι κάθε στοιχείο που προστίθεται στο API έχει τις δικές του πληροφορίες εκδοχής και προσδιοριστικού @since.

Τα εργαλεία παρέχουν την ακόλουθη επικύρωση για τα προσδιοριστικά @since:

Οι προτιμήσεις της διαχείρισης προσδιοριστικών @since μπορούν να τροποποιηθούν με τη χρήση της σελίδας προτιμήσεων Άνοιγμα της σελίδας προτιμήσεων κονσόλας Ανάπτυξη πρόσθετων λειτουργιών > Σφάλματα/Προειδοποιήσεις API.

Έλλειψη προσδιοριστικών @since

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

Για παράδειγμα, έχετε μια δέσμη A με εκδοχή 1.0.0 και προστίθεται μια κλάση C στην εκδοχή 1.1.0 της A, η οποία περιλαμβάνει μια μέθοδο m1().

Προσδιοριστικά @since εσφαλμένης μορφής

Στα νέα στοιχεία μπορεί να γίνει έλεγχος συνέπειας των προσδιοριστικών @since για να διασφαλιστεί ότι τα προσδιοριστικά έχουν τη σωστή μορφή. Τα εργαλεία API ελέγχουν ότι όλα τα προσδιοριστικά @since ακολουθούν την παρακάτω γενική μορφή:

[@since] [pre-amble] [2 part version] [post-amble]

Δείτε τα ακόλουθα παραδείγματα προσδιοριστικών @since:

Μη έγκυρες εκδοχές προσδιοριστικών @since

Στα νέα στοιχεία επίσης πραγματοποιείται έλεγχος εγκυρότητας των προσδιοριστικών @since. Ένα προσδιοριστικό @since θεωρείται έγκυρο αν οι πληροφορίες έκδοσης του προσδιοριστικού συμφωνούν με την έκδοση της δέσμης.

Δείτε το παρακάτω παράδειγμα, όπου έχει προστεθεί μια νέα μέθοδος m2() σε μια κλάση API στη δέσμη A εκδοχής 1.0.0:

Σχετικές εργασίες
Ρύθμιση γραμμής βάσης

Σχετικές παραπομπές
Προτιμήσεις γραμμών βάσης API
Προτιμήσεις σφαλμάτων και προειδοποιήσεων API