1// Ornek1: Javadoc — kodu belgeleyen özel yorumlar (/** ... */) ve etiketler.
2// Çalıştırma: java Ornek1.java   (sınıf çalışır; Javadoc yorumları 'javadoc' aracıyla HTML olur)
3public class Ornek1 {
4
5    /**
6     * İki tam sayıyı güvenli biçimde böler.
7     * <p>Bu metot, sıfıra bölme durumunda bir istisna fırlatır.</p>
8     *
9     * @param bolunen bölünecek sayı (pay)
10     * @param bolen   bölen sayı (payda); {@code 0} olamaz
11     * @return {@code bolunen / bolen} tam sayı bölümü
12     * @throws ArithmeticException {@code bolen} sıfır ise
13     * @see #carp(int, int)
14     */
15    public static int bol(int bolunen, int bolen) {
16        if (bolen == 0) throw new ArithmeticException("sıfıra bölme");
17        return bolunen / bolen;
18    }
19
20    /**
21     * İki sayıyı çarpar.
22     *
23     * @param a ilk çarpan
24     * @param b ikinci çarpan
25     * @return çarpım {@code a * b}
26     */
27    public static int carp(int a, int b) {
28        return a * b;
29    }
30
31    public static void main(String[] args) {
32        System.out.println("bol(20, 4) = " + bol(20, 4));
33        System.out.println("carp(6, 7) = " + carp(6, 7));
34        try {
35            bol(5, 0);
36        } catch (ArithmeticException e) {
37            System.out.println("bol(5, 0) -> " + e.getMessage() + " (Javadoc'ta @throws ile belgelendi)");
38        }
39
40        System.out.println("""
41
42                --- Javadoc temelleri ---
43                /** ... */ (üç değil ÇİFT yıldızla başlar) -> Javadoc yorumu; 'javadoc' aracı bunları HTML API dokümanına çevirir.
44                İlk cümle ÖZETtir (listelerde görünür). Blok etiketleri:
45                  @param ad açıklama   -> her parametre
46                  @return açıklama     -> dönüş değeri
47                  @throws Tip açıklama -> fırlatılan istisnalar
48                  @see / @since / @deprecated / @author / @version
49                Satır içi etiketler: {@code kod}, {@link Sınıf#metot}, {@literal}.
50                İyi Javadoc: NE yaptığını ve sözleşmesini (ön/son koşullar) anlatır; NASIL yapıldığını değil.""");
51    }
52}

1// Ornek2: Javadoc — sınıf/alan dokümantasyonu, @since/@deprecated ve satır içi etiketler.
2// Çalıştırma: java Ornek2.java
3public class Ornek2 {
4
5    /**
6     * Basit bir banka hesabını temsil eder.
7     * <p>
8     * Bakiye her zaman sıfır veya pozitiftir; {@link #cek(double)} bu kuralı korur.
9     *
10     * @author Eğitim Portalı
11     * @since 1.0
12     */
13    static class Hesap {
14        /** Hesabın güncel bakiyesi (TL). Asla negatif olmaz. */
15        private double bakiye;
16
17        /**
18         * Hesaba para yatırır.
19         *
20         * @param tutar yatırılacak tutar; pozitif olmalı
21         */
22        public void yatir(double tutar) {
23            if (tutar > 0) bakiye += tutar;
24        }
25
26        /**
27         * Bakiyeyi kontrol ederek para çeker.
28         *
29         * @param tutar çekilecek tutar
30         * @return işlem başarılıysa {@code true}, yetersiz bakiyede {@code false}
31         */
32        public boolean cek(double tutar) {
33            if (tutar > 0 && tutar <= bakiye) { bakiye -= tutar; return true; }
34            return false;
35        }
36
37        /**
38         * Bakiyeyi kuruş cinsinden döndürür.
39         *
40         * @return kuruş bakiye
41         * @deprecated Bunun yerine {@link #getBakiye()} kullanın (TL döndürür).
42         */
43        @Deprecated(since = "2.0")
44        public long getBakiyeKurus() { return (long) (bakiye * 100); }
45
46        /** @return TL cinsinden güncel bakiye */
47        public double getBakiye() { return bakiye; }
48    }
49
50    public static void main(String[] args) {
51        Hesap h = new Hesap();
52        h.yatir(1000);
53        System.out.println("çek(400) -> " + h.cek(400) + ", bakiye=" + h.getBakiye());
54        System.out.println("çek(800) -> " + h.cek(800) + " (yetersiz), bakiye=" + h.getBakiye());
55
56        System.out.println("""
57
58                --- Sınıf dokümantasyonu, @deprecated, satır içi etiketler ---
59                Sınıf/alan/metot HEPSİ Javadoc ile belgelenebilir. HTML (<p>, <ul>) kullanılabilir.
60                @since: hangi sürümde eklendi. @deprecated: neden kullanılmamalı + alternatif (genelde @Deprecated ile birlikte).
61                Satır içi {@link #metot}: başka bir öğeye tıklanabilir bağlantı (IDE'de gezinme).
62                ÜRETİM: 'javadoc -d docs *.java' ile HTML dok üretilir; Maven/Gradle eklentileriyle otomatikleşir.
63                Spring/JDK API dokümanları (docs.oracle.com) bu Javadoc'lardan üretilir.""");
64    }
65}