Powrót do poprzedniego menu.

II. Komentarze Javadoc.


Każdy element pliku Java: klasa, atrybuty klasy, metody klasy, konstruktory, etc. powinny być opisane za pomocą Javadoc.

Komentarz Javadoc powinien odpowiadać na 2 pytania zadane przez czytelnika/programistę:

Jeżeli komentarz Javadoc jest poprawnie napisany, to:
SUN opublikował przewodnik, jak poprawnie pisać Javadoc. Można go znaleźć tutaj.
Ponadto SUN udostępnia również narzędzie do sprawdzania poprawności Javadoc, które można znaleźć tutaj.

Mimo wszystko odwołuję do specyfikacji Javadoc by SUN. Poniżej znajduje się przykład klasy opisanej za pomocą Javadoc:
    /**
     * Torn Sp. z o.o.
     * 2008-04-22
     */
    package vcr2.common.transfer;
    
    import java.io.Serializable;
    import java.util.Collection;
    import java.util.LinkedList;
    
    /**
     * Klasa kontenerowa przechowująca listę pakietów medialnych.
* Wszystkie pakiety przechowywane przez {@link MediaPacketContainer} są * posortowane w kolejności wrzucania pakietów.
* W trakcie dodawania pakietów medialnych do tego kontenera ustawiana jest * flaga gotowości {@link MediaPacketContainer#isReady} do wysłania. * * @author Grzegorz Tymiński * @see MediaPacket * @see LinkedList */
public class MediaPacketContainer extends LinkedList implements Serializable { /** */ private static final long serialVersionUID = 5723698876880430191L; /** * Ile pakietów ({@value}) musi zawierać kontener, aby być gotowym do * wysłania. */ private transient static final int MINIMUM = 4; /** Flaga mówiąca, czy kontener jest gotowy do wysłania. */ private transient boolean isReady = false; /** Identyfikator użytkownika, który wygenerował pakiety medialne. */ private final long creatorId; /** * Czy pakiety, są pakietami audio. Jeżeli true to są to * pakiety audio. Jeżeli false to są to pakiety video. */ private final boolean isAudio; /** * Tworzy obiekt kontenera pakietów medialnych. * * @param creatorId * Identyfikator autora pakietów medialnych. * @param isAudio * Czy pakiety są pakietami audio. */ public MediaPacketContainer(long creatorId, boolean isAudio) { super(); this.creatorId = creatorId; this.isAudio = isAudio; } /** * @return true jeśli kontener jest gotowy do wysłania. W przeciwnym razie false. */ public boolean isReady() { return isReady; } /** * @return Identyfikator użytkownika, który wygenerował pakiety medialne. */ public long getCreatorId() { return creatorId; } /** * @return Czy pakiety są pakietami audio. */ public boolean isAudio() { return isAudio; } /** * @return Czy pakiety są pakietami video. */ public boolean isVideo() { return !isAudio; } /** * Metoda dodaje do listy pakiet medialny. Jego kolejność jest zachowana. * Jeżeli po dodaniu tego pakietu liczba pakietów w liście jest równa bądź * większa minimalnej liczbie możliwej do wysłania, wtedy flaga * {@link MediaPacketContainer#isReady} jest ustawiana na true. * * @param e * Pakiet medialny. * @return true tak, jak to zostało opisane przez * {@link Collection#add(Object)}. */ @Override public boolean add(MediaPacket e) { boolean added = super.add(e); if (added && size() > MINIMUM) { isReady = true; } return added; } /** * Metoda dodaje do listy wszystkie pakiety medialne znajdujące się w * kolekcji. Kolejność ich dodawania jest zachowana. Jeżeli po dodaniu tych * pakietów liczba pakietów w liście jest równa bądź większa minimalnej * liczbie możliwej do wysłania, wtedy flaga * {@link MediaPacketContainer#isReady} jest ustawiana na true. * * @param c * Kolekcja pakietów medialnych. * @return true tak, jak to zostało opisane przez * {@link Collection#addAll(Collection)}. */ @Override public boolean addAll(Collection c) { boolean added = super.addAll(c); if (added && size() > MINIMUM) { isReady = true; } return added; } /** * Metoda usuwa wszystkie pakiety medialne z listy. Flaga * {@link MediaPacketContainer#isReady} jest ustawiana na false. */ @Override public void clear() { isReady = false; super.clear(); } }

Powrót do poprzedniego menu.