Add comprehensive Javadoc comments to enhance code documentation and clarity

Author: bentahsin

src/main/java/com/bentahsin/regionshield/BenthRegionShield.java

@@ -22,6 +22,11 @@
 import java.util.concurrent.TimeUnit;
 import java.util.logging.Level;
 
+/**
+ * BenthRegionShield API'sinin ana sınıfı.
+ * Bu sınıf, birleşik bir arayüz aracılığıyla çeşitli bölge koruma eklentilerini (hook'lar)
+ * yönetmek ve sorgulamak için merkezi bir merkez görevi görür.
+ */
 public class BenthRegionShield {
 
     @Getter
@@ -42,6 +47,11 @@ public class BenthRegionShield {
     @Getter @Setter
     private String bypassPermission = "regionshield.bypass";
 
+    /**
+     * Yeni bir BenthRegionShield örneği oluşturur.
+     *
+     * @param plugin Bu API'ye sahip olan JavaPlugin örneği.
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP2")
     public BenthRegionShield(JavaPlugin plugin) {
         this.plugin = plugin;
@@ -58,6 +68,12 @@ public BenthRegionShield(JavaPlugin plugin) {
         plugin.getServer().getPluginManager().registerEvents(new RegionMovementListener(this), plugin);
     }
 
+    /**
+     * Yeni bir shield kancası (hook) kaydeder. Hook'lar, farklı bölge koruma eklentileriyle
+     * entegre olmak için kullanılır. Kaydedilen hook'lar öncelik değerine göre (en yüksekten en düşüğe) sıralanır.
+     *
+     * @param hook Kaydedilecek hook uygulaması.
+     */
     public void registerHook(IShieldHook hook) {
         if (hook == null) return;
 
@@ -71,15 +87,37 @@ public void registerHook(IShieldHook hook) {
         }
     }
 
+    /**
+     * Mevcut olarak kayıtlı tüm hook'ları kaldırır ve sonuç önbelleğini temizler.
+     */
     public void unregisterAll() {
         hooks.clear();
         resultCache.invalidateAll();
     }
 
+    /**
+     * Bir oyuncunun belirli bir konumda belirli bir etkileşimi gerçekleştirmesine izin verilip verilmediğini kontrol eder.
+     * Bu, basit bir boolean döndüren kullanışlı bir metottur.
+     *
+     * @param player   Etkileşimi gerçekleştiren oyuncu.
+     * @param location Etkileşimin gerçekleştiği konum.
+     * @param type     Gerçekleştirilen etkileşim türü.
+     * @return Oyuncunun etkileşimde bulunmasına izin veriliyorsa true, aksi takdirde false.
+     */
     public boolean canInteract(Player player, Location location, InteractionType type) {
         return checkResult(player, location, type).isAllowed();
     }
 
+    /**
+     * Bir oyuncunun bir konumda etkileşim kurup kuramayacağını görmek için ayrıntılı bir kontrol gerçekleştirir.
+     * Bu metot, bypass yetkilerini kontrol eder, önbelleğe bakar ve ardından kayıtlı tüm hook'ları
+     * öncelik sırasına göre sorgular. Eylemi reddeden ilk hook, sonucu belirler.
+     *
+     * @param player   Kontrol edilecek oyuncu.
+     * @param location Kontrol edilecek konum.
+     * @param type     Kontrol edilecek etkileşim türü.
+     * @return Etkileşimin sonucunu içeren bir {@link ShieldResponse} nesnesi.
+     */
     public ShieldResponse checkResult(Player player, Location location, InteractionType type) {
         if (player.hasPermission(bypassPermission) || player.isOp()) {
             return ShieldResponse.allow();
@@ -123,6 +161,13 @@ public ShieldResponse checkResult(Player player, Location location, InteractionT
         return allowed;
     }
 
+    /**
+     * Belirli bir konumdaki bölge hakkında bilgi alır.
+     * Hook'ları öncelik sırasına göre sorgular ve bir bölge tanımlayan ilk hook'tan gelen bilgiyi döndürür.
+     *
+     * @param location Bilgi alınacak konum.
+     * @return Bir {@link RegionInfo} nesnesi veya bölge bulunamazsa null.
+     */
     public RegionInfo getRegionInfo(Location location) {
         for (IShieldHook hook : hooks) {
             try {
@@ -135,11 +180,24 @@ public RegionInfo getRegionInfo(Location location) {
         return null;
     }
 
+    /**
+     * Adına göre belirli bir hook'tan bölge bilgilerini alır.
+     *
+     * @param hookName   Bilgiyi sağlayacak hook'un adı.
+     * @param location   Bilgi alınacak konum.
+     * @return Bir {@link RegionInfo} nesnesi veya hook bulunamazsa/bölge yoksa null.
+     */
     public RegionInfo getRegionInfo(String hookName, Location location) {
         IShieldHook hook = getHook(hookName);
         return (hook != null) ? hook.getRegionInfo(location) : null;
     }
 
+    /**
+     * Oyuncunun o anda içinde bulunduğu bölgenin sınırlarını görsel olarak (parçacıklarla) gösterir.
+     * Sınırlar, oyuncunun konumunda bir bölge tanımlayan en yüksek öncelikli hook tarafından sağlanır.
+     *
+     * @param player Sınırları görecek oyuncu.
+     */
     public void showBoundaries(Player player) {
         Location loc = player.getLocation();
         RegionBounds bounds = null;
@@ -162,18 +220,38 @@ public void showBoundaries(Player player) {
         RegionVisualizer.show(plugin, player, bounds);
     }
 
+    /**
+     * Kayıtlı bir hook'u benzersiz adına göre alır.
+     *
+     * @param name Alınacak hook'un adı (büyük/küçük harfe duyarsız).
+     * @return {@link IShieldHook} örneği veya bulunamazsa null.
+     */
     public IShieldHook getHook(String name) {
         return hooks.stream()
                 .filter(h -> h.getName().equalsIgnoreCase(name))
                 .findFirst()
                 .orElse(null);
     }
 
+    /**
+     * Tek bir hook'u adına göre kayıttan kaldırır ve tüm önbelleği geçersiz kılar.
+     *
+     * @param name Kayıttan kaldırılacak hook'un adı (büyük/küçük harfe duyarsız).
+     */
     public void unregisterHook(String name) {
         hooks.removeIf(hook -> hook.getName().equalsIgnoreCase(name));
         resultCache.invalidateAll();
     }
 
+    /**
+     * Diğerlerini yoksayarak yalnızca belirli, adlandırılmış bir hook'u kullanarak bir etkileşim kontrolü gerçekleştirir.
+     *
+     * @param hookName   Kullanılacak hook'un adı.
+     * @param player     Kontrol edilecek oyuncu.
+     * @param location   Kontrol edilecek konum.
+     * @param type       Kontrol edilecek etkileşim türü.
+     * @return Hook tarafından döndürülen {@link ShieldResponse} veya hook bulunamazsa izin veren bir response.
+     */
     public ShieldResponse checkSpecific(String hookName, Player player, Location location, InteractionType type) {
         IShieldHook hook = getHook(hookName);
         if (hook == null) return ShieldResponse.allow();
@@ -191,18 +269,27 @@ private void logDebug(Player player, String provider) {
     }
 
     /**
-     * Çağrıldığı metodu Annotation açısından denetler.
-     * Kullanım: if (!api.guard(this, "metodIsmi", player)) return;
+     * Çağrıldığı metodu RegionShield ek açıklamaları (annotations) açısından denetler.
+     * Bu, geliştiricilerin kodlarını kolayca bölge korumasına almasını sağlayan güçlü bir özelliktir.
+     * <p>
+     * Kullanım: {@code if (!api.guard(this, "metodIsmi", player)) return;}
+     *
+     * @param instance   Metodun ait olduğu nesne örneği.
+     * @param methodName Denetlenecek metodun adı.
+     * @param player     Kontrolün yapılacağı oyuncu.
+     * @param paramTypes Metodun parametre türleri (metot overload durumları için).
+     * @return Oyuncunun metoda devam etmesine izin veriliyorsa true, engellendiyse false.
      */
     public boolean guard(Object instance, String methodName, Player player, Class<?>... paramTypes) {
         return gate.inspect(instance, methodName, player, paramTypes);
     }
 
     /**
-     * Bir bölgeye oyuncu limiti koyar.
-     * @param provider Eklenti ismi (WorldGuard, Towny vb.)
-     * @param regionId Bölge ID'si
-     * @param limit Maksimum oyuncu sayısı
+     * Bir bölgeye oyuncu limiti koyar. Belirtilen bölgeye girebilecek maksimum oyuncu sayısını ayarlar.
+     *
+     * @param provider Eklenti ismi (Örn: "WorldGuard", "Towny"). Bu, hook adıyla eşleşmelidir.
+     * @param regionId Bölgenin kimliği (ID).
+     * @param limit    Bu bölge için maksimum oyuncu sayısı.
      */
     public void setRegionLimit(String provider, String regionId, int limit) {
         limitManager.setLimit(provider, regionId, limit);

src/main/java/com/bentahsin/regionshield/internal/ReflectionUtils.java

@@ -8,17 +8,24 @@
 import java.lang.reflect.Method;
 
 /**
- * Java Reflection işlemlerini güvenli ve temiz bir şekilde yapmak için yardımcı araçlar.
- * try-catch bloklarını tek bir yerde toplar ve kod kirliliğini önler.
+ * Java Reflection (Yansıtma) işlemlerini basitleştirmek ve güvenli hale getirmek için bir dizi statik yardımcı metot sağlar.
+ * <p>
+ * Bu sınıfın temel amacı, yansıtma ile ilişkili istisna yönetimini (try-catch blokları) merkezileştirerek
+ * kod tekrarını önlemek ve proje genelinde okunabilirliği artırmaktır. Tüm metotlar,
+ * bir hata durumunda istisna fırlatmak yerine null döndürür, bu da kullanımı kolaylaştırır.
+ * <p>
+ * Bir {@link UtilityClass} olarak bu sınıfın bir örneği oluşturulamaz.
  */
 @UtilityClass
 @SuppressFBWarnings("REFLF_REFLECTION_MAY_INCREASE_ACCESSIBILITY_OF_FIELD")
 public class ReflectionUtils {
 
     /**
-     * İsmi verilen sınıfı bulmaya çalışır.
-     * @param className Sınıfın tam paket adı (örn: com.sk89q.worldguard.WorldGuard)
-     * @return Sınıf bulunursa Class objesi, bulunamazsa null.
+     * Tam nitelikli adına göre bir sınıfı güvenli bir şekilde bulmaya ve yüklemeye çalışır.
+     * Bu metot, {@link ClassNotFoundException} istisnasını kapsüller.
+     *
+     * @param className Sınıfın tam paket adı (örneğin: "com.sk89q.worldguard.WorldGuard").
+     * @return Sınıf bulunursa {@link Class} nesnesi, bulunamazsa null.
      */
     public Class<?> getClass(String className) {
         try {
@@ -29,11 +36,14 @@ public Class<?> getClass(String className) {
     }
 
     /**
-     * Bir sınıftaki metodu ismine ve parametrelerine göre bulur.
-     * @param clazz Aranacak sınıf
-     * @param methodName Metod adı
-     * @param parameterTypes Metodun parametre tipleri
-     * @return Metod bulunursa Method objesi, bulunamazsa null.
+     * Verilen bir sınıfta, adına ve parametre türlerine göre bir metot bulur.
+     * Özel veya korumalı metotlara erişime izin vermek için bulunan metot üzerinde
+     * otomatik olarak {@code setAccessible(true)} çağrısı yapar.
+     *
+     * @param clazz          Metodun aranacağı sınıf.
+     * @param methodName     Aranacak metodun adı.
+     * @param parameterTypes Metodun sahip olduğu parametrelerin türleri.
+     * @return Metot bulunursa {@link Method} nesnesi, bulunamazsa null.
      */
     public Method getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) {
         if (clazz == null) return null;
@@ -47,11 +57,13 @@ public Method getMethod(Class<?> clazz, String methodName, Class<?>... parameter
     }
 
     /**
-     * Bir metodu güvenli bir şekilde çalıştırır.
-     * @param method Çalıştırılacak metod
-     * @param instance Hangi obje üzerinde çalışacak? (Static metodlar için null olabilir)
-     * @param args Metoda gönderilecek parametreler
-     * @return Metodun dönüş değeri (Object) veya hata durumunda null.
+     * Belirtilen argümanlarla, verilen bir örnek üzerinde bir metodu güvenli bir şekilde çağırır.
+     * Metot çağrımı sırasında fırlatılan herhangi bir istisna yakalanır ve metot null döndürür.
+     *
+     * @param method   Çalıştırılacak olan {@link Method} nesnesi.
+     * @param instance Metodun çağrılacağı nesne örneği. Statik metotlar için bu değer null olabilir.
+     * @param args     Metoda geçirilecek olan argümanlar (parametreler).
+     * @return Metodun dönüş değeri veya bir hata oluşursa null. Eğer metodun dönüş tipi void ise null döner.
      */
     public Object invoke(Method method, Object instance, Object... args) {
         if (method == null) return null;
@@ -63,11 +75,13 @@ public Object invoke(Method method, Object instance, Object... args) {
     }
 
     /**
-     * Bir sınıfın içindeki alanın (field/değişken) değerini okur.
-     * @param clazz Sınıf
-     * @param instance Obje örneği
-     * @param fieldName Değişken adı
-     * @return Değişkenin değeri
+     * Verilen bir örnekten bir alanın (field) değerini güvenli bir şekilde okur.
+     * Bu metot, {@code getDeclaredField} kullanarak ve erişilebilir olarak ayarlayarak özel alanlara erişebilir.
+     *
+     * @param clazz     Alanın bulunduğu sınıf.
+     * @param instance  Değerin okunacağı nesne örneği.
+     * @param fieldName Değeri okunacak olan alanın adı.
+     * @return Alanın değeri veya bir hata oluşursa (örn: alan bulunamadı) null.
      */
     public Object getField(Class<?> clazz, Object instance, String fieldName) {
         if (clazz == null) return null;
@@ -82,7 +96,9 @@ public Object getField(Class<?> clazz, Object instance, String fieldName) {
 
     /**
      * Bir eklentinin sunucuda yüklü ve aktif olup olmadığını kontrol eder.
-     * @param pluginName Eklenti adı (plugin.yml içindeki name)
+     *
+     * @param pluginName Eklentinin adı (plugin.yml dosyasındaki 'name' değeri).
+     * @return Eklenti aktif ise true, değilse false.
      */
     public boolean isPluginActive(String pluginName) {
         return Bukkit.getPluginManager().isPluginEnabled(pluginName);