feat: Add caching and middleware support for placeholders, enhance documentation generation

.gitignore

@@ -36,4 +36,6 @@ build/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+
+dependency-reduced-pom.xml

src/main/java/com/bentahsin/benthpapimanager/annotations/Cache.java

@@ -0,0 +1,29 @@
+package com.bentahsin.benthpapimanager.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Bir placeholder metodunun sonucunun ne kadar süreyle önbelleğe alınacağını belirtir.
+ * Sık değişmeyen veriler için performansı artırır.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Cache {
+
+    /**
+     * Önbelleğin geçerlilik süresi.
+     * @return Süre değeri.
+     */
+    long duration();
+
+    /**
+     * Sürenin zaman birimi (saniye, dakika vb.).
+     * Varsayılan olarak saniyedir.
+     * @return Zaman birimi.
+     */
+    TimeUnit unit() default TimeUnit.SECONDS;
+}

src/main/java/com/bentahsin/benthpapimanager/annotations/Middleware.java

@@ -0,0 +1,24 @@
+package com.bentahsin.benthpapimanager.annotations;
+
+import com.bentahsin.benthpapimanager.middleware.PlaceholderMiddleware;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Bir placeholder metodunun sonucunu, PAPI'ye döndürmeden önce
+ * işleyecek olan bir veya daha fazla ara katman sınıfını belirtir.
+ * Bu, sonuçları formatlamak veya değiştirmek için kullanılır.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Middleware {
+    /**
+     * Sonucu işleyecek olan PlaceholderMiddleware arayüzünü uygulayan sınıflar.
+     * Birden fazla middleware belirtilirse, sırayla uygulanırlar.
+     * @return Middleware sınıfları.
+     */
+    Class<? extends PlaceholderMiddleware>[] value();
+}

src/main/java/com/bentahsin/benthpapimanager/annotations/PlaceholderIdentifier.java

@@ -38,4 +38,16 @@
      * @return Yükleniyor metni.
      */
     String onLoading() default "§eHesaplanıyor...§r";
+
+    /**
+     * Placeholder açıklaması için opsiyonel alan
+     * @return Açıklama
+     */
+    String description() default "";
+
+    /**
+     * Örnek kullanım için opsiyonel alan
+     * @return Örnek
+     */
+    String example() default "";
 }

src/main/java/com/bentahsin/benthpapimanager/annotations/RelationalPlaceholder.java

@@ -37,4 +37,16 @@
      * @return Yükleniyor metni.
      */
     String onLoading() default "§eHesaplanıyor...§r";
+
+    /**
+     * Placeholder açıklaması için opsiyonel alan
+     * @return Açıklama
+     */
+    String description() default "";
+
+    /**
+     * Örnek kullanım için opsiyonel alan
+     * @return Örnek
+     */
+    String example() default "";
 }

src/main/java/com/bentahsin/benthpapimanager/annotations/RequirePermission.java

@@ -0,0 +1,24 @@
+package com.bentahsin.benthpapimanager.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Bir placeholder'ı kullanmak için oyuncunun sahip olması gereken yetkiyi belirtir.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface RequirePermission {
+    /**
+     * Gerekli yetki düğümü (örn: "admin.see.ram").
+     */
+    String value();
+
+    /**
+     * Oyuncunun yetkisi yoksa döndürülecek mesaj.
+     * Boş bırakılırsa hiçbir şey döndürmez (boş string).
+     */
+    String onDeny() default "";
+}

src/main/java/com/bentahsin/benthpapimanager/middleware/PlaceholderMiddleware.java

@@ -0,0 +1,15 @@
+package com.bentahsin.benthpapimanager.middleware;
+
+/**
+ * Placeholder'dan dönen ham veriyi işlemek için bir arayüz.
+ * Bu arayüzü uygulayan sınıflar, @Middleware anotasyonu ile kullanılabilir.
+ */
+@FunctionalInterface
+public interface PlaceholderMiddleware {
+    /**
+     * Placeholder metodundan gelen ham sonucu işler ve formatlanmış bir String döndürür.
+     * @param input Placeholder metodunun orijinal dönüş değeri (örn: Integer, Double, String).
+     * @return Formatlanmış veya işlenmiş sonuç.
+     */
+    String process(Object input);
+}