From 4424e6ce8f9a184203f1f9ad03ea5bc42217a22d Mon Sep 17 00:00:00 2001
From: Snabeldier <79211348+Snabeldier@users.noreply.github.com>
Date: Sun, 5 Jan 2025 01:16:42 +0100
Subject: [PATCH] add some documentation

---
 src/main/java/minevalley/core/api/Core.java   | 30 ++++++++++++++++++-
 .../java/minevalley/core/api/CoreServer.java  |  2 +-
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java
index 2f39ba89..2b8d7526 100644
--- a/src/main/java/minevalley/core/api/Core.java
+++ b/src/main/java/minevalley/core/api/Core.java
@@ -177,17 +177,45 @@ public static BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonn
         return server.runAsyncTaskPeriodically(delay, period, task);
     }
 
+    /**
+     * Create a {@link StatementBuilder} based on the given SQL code.
+     *
+     * @param sql SQL code to prepare
+     * @return a new {@link StatementBuilder} instance
+     * @throws SQLException if a database access error occurs
+     */
     @Nonnull
+    @Contract("_ -> new")
     public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) throws SQLException {
         return server.prepareSQL(sql, false);
     }
 
+    /**
+     * Create a {@link StatementBuilder} based on the given SQL code.
+     *
+     * @param sql                   SQL code to prepare
+     * @param retrieveGeneratedKeys whether to retrieve generated keys
+     * @return a new {@link StatementBuilder} instance
+     * @throws SQLException if a database access error occurs
+     */
     @Nonnull
+    @Contract("_, _ -> new")
     public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException {
         return server.prepareSQL(sql, retrieveGeneratedKeys);
     }
 
-    public static int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException {
+    /**
+     * Generate a random id based on the given length that was not used in the given column and table.
+     *
+     * @param table         table to check
+     * @param column        column to check
+     * @param amountOfChars amount of chars the id should have
+     * @return a unique id
+     * @throws IllegalArgumentException if the table is null, column is null or the amount of chars is less than 1
+     * @throws SQLException             if a database access error occurs
+     */
+    @Contract("_, _, _ -> _")
+    public static int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException, SQLException {
         return server.generateUniqueId(table, column, amountOfChars);
     }
 
diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java
index 9627d64f..4b6eb23a 100644
--- a/src/main/java/minevalley/core/api/CoreServer.java
+++ b/src/main/java/minevalley/core/api/CoreServer.java
@@ -86,7 +86,7 @@ public interface CoreServer {
     @Nonnull
     StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException;
 
-    int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException;
+    int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException, SQLException;
 
     void registerListener(@Nonnull Class<? extends Event> cls, @Nonnull EventListener<? extends Event> listener) throws IllegalArgumentException;