added more docs

Author: david

src/main/java/net/onelitefeather/bettergopaint/brush/BrushSettings.java

@@ -22,16 +22,17 @@
 import net.onelitefeather.bettergopaint.objects.other.SurfaceMode;
 import org.bukkit.Axis;
 import org.bukkit.Material;
-import org.bukkit.inventory.meta.ItemMeta;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.Arrays;
 import java.util.List;
-import java.util.Objects;
-import java.util.Optional;
 import java.util.Random;
 
+/**
+ * The BrushSettings interface defines the configuration settings for a brush. It provides methods to retrieve information
+ * about the brush's axis, brush type, list of blocks, mask material, enabled status, surface mode, angle-height
+ * difference, angle distance, chance, falloff strength, fracture distance, mixing strength, size and thickness.
+ */
 public interface BrushSettings {
 
     /**

src/main/java/net/onelitefeather/bettergopaint/brush/PlayerBrush.java

@@ -49,6 +49,9 @@
 import java.util.Random;
 import java.util.stream.Collectors;
 
+/**
+ * The PlayerBrush class represents the brush settings of a player.
+ */
 public final class PlayerBrush implements BrushSettings {
 
     private final @NotNull PlayerBrushManager brushManager;

src/main/java/net/onelitefeather/bettergopaint/brush/PlayerBrushManager.java

@@ -41,6 +41,9 @@
 import java.util.UUID;
 import java.util.stream.Collectors;
 
+/**
+ * The PlayerBrushManager class manages the brush selection for each player.
+ */
 public class PlayerBrushManager {
 
     private final @NotNull HashMap<UUID, PlayerBrush> playerBrushes = new HashMap<>();
@@ -58,12 +61,23 @@ public class PlayerBrushManager {
             new PaintBrush()
     );
 
-    public PlayerBrush getBrush(@NotNull Player player) {
+    /**
+     * Retrieves the brush for the given player.
+     *
+     * @param player The player for which to retrieve the brush.
+     * @return The brush for the specified player.
+     */
     public @NotNull PlayerBrush getBrush(@NotNull Player player) {
         return playerBrushes.computeIfAbsent(player.getUniqueId(), ignored -> new PlayerBrush(this));
     }
 
-    public String getBrushLore(@NotNull Brush brush) {
+    /**
+     * Retrieves the lore for a specific brush. Each brush name is preceded by a color code
+     * indicating whether it is the currently selected brush or not.
+     *
+     * @param brush The brush for which to retrieve the lore.
+     * @return The lore for the specified brush.
+     */
     public @NotNull String getBrushLore(@NotNull Brush brush) {
         return brushes.stream().map(current -> {
             if (current.equals(brush)) {
@@ -74,21 +88,42 @@ public String getBrushLore(@NotNull Brush brush) {
         }).collect(Collectors.joining());
     }
 
+    /**
+     * Retrieves the brush handler for the given name.
+     *
+     * @param name The name of the brush to look for.
+     * @return An optional containing the brush handler, or empty if not found.
+     */
     public @NotNull Optional<Brush> getBrushHandler(String name) {
         return brushes.stream()
                 .filter(brush -> brush.getName().contains(name))
                 .findAny();
     }
 
+    /**
+     * Retrieves the list of available brushes.
+     *
+     * @return The list of available brushes.
+     */
     public @NotNull List<Brush> getBrushes() {
         return brushes;
     }
 
+    /**
+     * Removes the player from the {@link #playerBrushes} map.
+     *
+     * @param player The player who should be removed.
+     */
     public void removeBrush(@NotNull Player player) {
         playerBrushes.remove(player.getUniqueId());
     }
 
-    public Brush cycleForward(@Nullable Brush brush) {
+    /**
+     * Retrieves the next brush in the list of available brushes.
+     *
+     * @param brush The current brush, if null returns the first brush in the list.
+     * @return The next brush in the list, or the first brush if the current brush is null.
+     */
     public @NotNull Brush cycleForward(@Nullable Brush brush) {
         if (brush == null) {
             return brushes.getFirst();
@@ -100,7 +135,12 @@ public Brush cycleForward(@Nullable Brush brush) {
         return brushes.getFirst();
     }
 
-    public Brush cycleBack(@Nullable Brush brush) {
+    /**
+     * Retrieves the previous brush in the list of available brushes.
+     *
+     * @param brush The current brush.
+     * @return The previous brush in the list, or the first brush if the current brush is null.
+     */
     public @NotNull Brush cycleBack(@Nullable Brush brush) {
         if (brush == null) {
             return brushes.getFirst();

src/main/java/net/onelitefeather/bettergopaint/utils/ConnectedBlocks.java

@@ -41,6 +41,14 @@ public class ConnectedBlocks {
             BlockFace.DOWN,
     };
 
+    /**
+     * Returns a stream of connected blocks starting from a given location, based on a list of blocks.
+     * Only blocks of the same type as the start block are considered.
+     *
+     * @param loc    the starting location
+     * @param blocks the list of blocks to check for connectivity
+     * @return a stream of connected blocks
+     */
     public static Stream<Block> getConnectedBlocks(Location loc, List<Block> blocks) {
         Block startBlock = loc.getBlock();
         Set<Block> connected = new HashSet<>();

src/main/java/net/onelitefeather/bettergopaint/utils/Sphere.java

@@ -29,6 +29,15 @@
 
 public class Sphere {
 
+    /**
+     * Returns a stream of blocks within a specified radius from a given middle point.
+     *
+     * @param middlePoint The middle point from which to calculate the radius.
+     * @param radius      The radius value.
+     * @param axis        The axis along which to calculate the radius (optional).
+     * @param air         Whether air blocks should be included.
+     * @return A stream of blocks within the specified radius.
+     */
     public static Stream<Block> getBlocksInRadius(Location middlePoint, int radius, @Nullable Axis axis, boolean air) {
         List<Block> blocks = new ArrayList<>();
         Location loc1 = middlePoint.clone().add(-radius / 2d, -radius / 2d, -radius / 2d).getBlock().getLocation();