From 2d3a1385f13af450ab7a2d2e4d92f9d4793e87cb Mon Sep 17 00:00:00 2001
From: David <github@nonswag.dev>
Date: Mon, 17 Mar 2025 10:53:06 +0100
Subject: [PATCH] [ci skip] Refine recipe management API documentation.
 (#12287)

* Refine recipe management API documentation.

Improve Javadoc clarity for recipe addition methods, specifying client update behavior and stability considerations. Adjust formatting for better readability and consistency.

* Fix typo in original javadoc

---------

Co-authored-by: david <mrminecraft00@gmail.com>
---
 paper-api/src/main/java/org/bukkit/Bukkit.java | 11 +++++++----
 paper-api/src/main/java/org/bukkit/Server.java | 14 ++++++--------
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java
index a371da9d1..db47fe656 100644
--- a/paper-api/src/main/java/org/bukkit/Bukkit.java
+++ b/paper-api/src/main/java/org/bukkit/Bukkit.java
@@ -1117,20 +1117,24 @@ public final class Bukkit {
 
     /**
      * Adds a recipe to the crafting manager.
+     * Recipes added with this method won't be sent to the client automatically.
+     * <p>
+     * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
+     * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
-     * @return true if the recipe was added, false if it wasn't for some
-     *     reason
+     * @return true if the recipe was added, false if it wasn't for some reason
+     * @see #addRecipe(Recipe, boolean)
      */
     @Contract("null -> false")
     public static boolean addRecipe(@Nullable Recipe recipe) {
         return server.addRecipe(recipe);
     }
 
-    // Paper start - method to send recipes immediately
     /**
      * Adds a recipe to the crafting manager.
      *
+     * @apiNote resendRecipes is ignored at the moment for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
      * @param resendRecipes true to update the client with the full set of recipes
      * @return true if the recipe was added, false if it wasn't for some reason
@@ -1139,7 +1143,6 @@ public final class Bukkit {
     public static boolean addRecipe(@Nullable Recipe recipe, boolean resendRecipes) {
         return server.addRecipe(recipe, resendRecipes);
     }
-    // Paper end - method to send recipes immediately
 
     /**
      * Get a list of all recipes for a given item. The stack size is ignored
diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java
index d7ebfcfc6..2eb72a31c 100644
--- a/paper-api/src/main/java/org/bukkit/Server.java
+++ b/paper-api/src/main/java/org/bukkit/Server.java
@@ -988,26 +988,24 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
     public boolean dispatchCommand(@NotNull CommandSender sender, @NotNull String commandLine) throws CommandException;
 
     /**
-     * Adds a recipe to the crafting manager. Recipes added with
-     * this method won't be sent to the client automatically. Use
-     * {@link #updateRecipes()} or {@link #updateResources()} to
-     * update clients to new recipes added.
+     * Adds a recipe to the crafting manager.
+     * Recipes added with this method won't be sent to the client automatically.
      * <p>
-     * Player's still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
+     * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
      * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
-     * @return true if the recipe was added, false if it wasn't for some
-     *     reason
+     * @return true if the recipe was added, false if it wasn't for some reason
      * @see #addRecipe(Recipe, boolean)
      */
     @Contract("null -> false")
-    public boolean addRecipe(@Nullable Recipe recipe);
+    boolean addRecipe(@Nullable Recipe recipe);
 
     // Paper start - method to send recipes immediately
     /**
      * Adds a recipe to the crafting manager.
      *
+     * @apiNote resendRecipes is ignored for now for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
      * @param resendRecipes true to update the client with the full set of recipes
      * @return true if the recipe was added, false if it wasn't for some reason