Τα εργαλεία API παρέχουν υποστήριξη για τη διαχείριση των προσδιοριστικών Javadoc
@since σε νέα στοιχεία που έχουν προστεθεί στο API (είδη, μεθόδους, πεδία,
κλπ.).
Τα νέα στοιχεία API μπορεί να είναι νέα είδη που έχουν προστεθεί σε ένα πακέτο API ή νέα
είδη, μέθοδοι ή πεδία που έχουν προστεθεί σε ένα είδος API.
Η προσθήκη μεθόδου αποτελεί μια ξεχωριστή περίπτωση κατά την οποία προστίθεται
μια μέθοδος σε ένα είδος αντικαθιστώντας μια μέθοδο γονικής κλάσης,
υλοποιώντας μια μέθοδο γονικής διεπαφής ή αλλάζοντας την υπογραφή μιας υπάρχουσας μεθόδου.
Σημείωση: Οι πληροφορίες του προσδιοριστικού @since δεν κληροδοτούνται κατά
την υλοποίησης ή τη δημιουργία υποκλάσεων. Θεωρείται δεδομένο ότι κάθε στοιχείο που προστίθεται
στο API έχει τις δικές του πληροφορίες εκδοχής και προσδιοριστικού @since.
Τα εργαλεία παρέχουν την ακόλουθη επικύρωση για τα προσδιοριστικά @since:
@since @since εσφαλμένης μορφής@sinceΟι προτιμήσεις της διαχείρισης προσδιοριστικών @since μπορούν να
τροποποιηθούν με τη χρήση της σελίδας προτιμήσεων
Ανάπτυξη πρόσθετων λειτουργιών > Σφάλματα/Προειδοποιήσεις API.
Κάθε νέο στοιχείο API που εντοπίζεται, ελέγχεται από τα εργαλεία για να διασφαλιστεί
η ύπαρξη του προσδιοριστικού @since.
Αν το νέο στοιχείο δεν έχει προσδιοριστικό @since, επισημαίνεται η έλλειψη με
έναν ενδείκτη και προτείνεται εκδοχή για το προσδιοριστικό.
Η προτεινόμενη εκδοχή για το νέο προσδιοριστικό θα είναι ίδια με την τρέχουσα εκδοχή
της δέσμης, εκτός από την περίπτωση αλλαγών που προκαλούν σφάλματα συμβατότητας στο API, κατά την οποία πρέπει να
ενημερωθεί και η εκδοχή δέσμης. Αν πρέπει να ενημερωθεί η εκδοχή δέσμης, η
προτεινόμενη εκδοχή για το προσδιοριστικό @since που λείπει θα είναι ίδια με
την προτεινόμενη εκδοχή δέσμης.
Για παράδειγμα, έχετε μια δέσμη A με εκδοχή 1.0.0 και προστίθεται μια κλάση C στην εκδοχή 1.1.0 της A, η οποία περιλαμβάνει μια μέθοδο m1().
@since στη m2() και θα
προτείνουν την τοποθέτηση ενός νέου προσδιοριστικού @since 1.1 στη m2().@since στη m2()
και θα προτείνουν την τοποθέτηση ενός νέου προσδιοριστικού @since 2.0 στη
m2(), όπου 2.0.0 είναι η νέα προτεινόμενη εκδοχή δέσμης.
Στα νέα στοιχεία μπορεί να γίνει έλεγχος συνέπειας των προσδιοριστικών
@since για να διασφαλιστεί ότι τα προσδιοριστικά έχουν τη σωστή μορφή. Τα
εργαλεία API ελέγχουν ότι όλα τα προσδιοριστικά @since ακολουθούν την
παρακάτω γενική μορφή:
[@since] [pre-amble] [2 part version] [post-amble]
Δείτε τα ακόλουθα παραδείγματα προσδιοριστικών @since:
@since A 1 added m2(): θα επισημαινόταν ως προσδιοριστικό εσφαλμένης μορφής επειδή λείπει το δεύτερο τμήμα από την εκδοχή@since: θα επισημαινόταν ως προσδιοριστικό εσφαλμένης μορφής επειδή δεν υπάρχουν πληροφορίες εκδοχής@since A: θα επισημαινόταν επειδή δεν περιλαμβάνει πληροφορίες εκδοχής@since 1.0.0: θα επισημαινόταν επειδή η εκδοχή έχει πολλά τμήματα@since A 1.0 added m2(): δεν θα επισημαινόταν
Στα νέα στοιχεία επίσης πραγματοποιείται έλεγχος εγκυρότητας των προσδιοριστικών @since. Ένα
προσδιοριστικό @since θεωρείται έγκυρο αν οι πληροφορίες έκδοσης του
προσδιοριστικού συμφωνούν με την έκδοση της δέσμης.
Δείτε το παρακάτω παράδειγμα, όπου έχει προστεθεί μια νέα μέθοδος m2() σε μια κλάση API στη δέσμη A εκδοχής 1.0.0:
@since A 1.0 added method m2() θεωρείται έγκυρο@since A 2.0 added method m2() δεν είναι έγκυρο επειδή η εκδοχή της δέσμης A είναι 1.0.0@since A 0.1 added method m2() δεν είναι έγκυρο επειδή η εκδοχή της δέσμης A είναι 1.0.0

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