add some documentation

MineValley · Jan 5, 2025 · 4424e6c · 4424e6c
1 parent f815f06
commit 4424e6c
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 2 deletions.
diff --git 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
@@ -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;