From f7fe7d8ec08eb9745169d124aac5f1f920718037 Mon Sep 17 00:00:00 2001
From: isXander <xander@isxander.dev>
Date: Wed, 5 Apr 2023 10:00:45 +0100
Subject: [PATCH] binding api full javadoc

---
 .../api/bind/ControlifyBindingsApi.java       | 12 ++++
 .../api/bind/ControllerBindingBuilder.java    | 58 +++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/src/main/java/dev/isxander/controlify/api/bind/ControlifyBindingsApi.java b/src/main/java/dev/isxander/controlify/api/bind/ControlifyBindingsApi.java
index 0e4f7e3..f0e6a86 100644
--- a/src/main/java/dev/isxander/controlify/api/bind/ControlifyBindingsApi.java
+++ b/src/main/java/dev/isxander/controlify/api/bind/ControlifyBindingsApi.java
@@ -16,6 +16,12 @@ import java.util.function.UnaryOperator;
  * Should be called within {@link dev.isxander.controlify.api.entrypoint.ControlifyEntrypoint#onControlifyPreInit(ControlifyApi)}
  */
 public interface ControlifyBindingsApi {
+    /**
+     * Registers a custom binding for all controllers.
+     * @param id the identifier for the binding, the namespace should be your modid.
+     * @param builder the binding builder function
+     * @return the binding supplier to fetch the binding for a specific controller.
+     */
     BindingSupplier registerBind(ResourceLocation id, UnaryOperator<ControllerBindingBuilder<?>> builder);
 
     /**
@@ -42,6 +48,12 @@ public interface ControlifyBindingsApi {
     @Deprecated
     BindingSupplier registerBind(GamepadBinds bind, ResourceLocation id, KeyMapping override, BooleanSupplier toggleOverride);
 
+    /**
+     * By default, all modded keybindings are registered as controller binds.
+     * If you are explicitly depending on Controlify, you should exclude all your
+     * keybindings and register them explicitly.
+     * @param keyMapping the mappings to exclude
+     */
     void excludeVanillaBind(KeyMapping... keyMapping);
 
     static ControlifyBindingsApi get() {
diff --git a/src/main/java/dev/isxander/controlify/api/bind/ControllerBindingBuilder.java b/src/main/java/dev/isxander/controlify/api/bind/ControllerBindingBuilder.java
index 90f4da7..ac07434 100644
--- a/src/main/java/dev/isxander/controlify/api/bind/ControllerBindingBuilder.java
+++ b/src/main/java/dev/isxander/controlify/api/bind/ControllerBindingBuilder.java
@@ -16,22 +16,80 @@ public interface ControllerBindingBuilder<T extends ControllerState> {
         return new ControllerBinding.ControllerBindingBuilderImpl<>(controller);
     }
 
+    /**
+     * Sets the identifier for the binding.
+     * @param id the identifier for the binding, the namespace should be your modid.
+     */
     ControllerBindingBuilder<T> identifier(ResourceLocation id);
 
+    /**
+     * Sets the identifier for the binding.
+     * @param namespace the namespace for the binding, should be your modid.
+     * @param path the path for the binding.
+     */
     ControllerBindingBuilder<T> identifier(String namespace, String path);
 
+    /**
+     * The default bind for the binding. This is usually inaccessible due to unknown
+     * generics and {@link ControllerBindingBuilder#defaultBind(GamepadBinds)} should be used instead.
+     * @param bind the default bind
+     */
     ControllerBindingBuilder<T> defaultBind(IBind<T> bind);
 
+    /**
+     * Sets the default gamepad bind for the binding.
+     * If the controller is not a gamepad, the default is unbound.
+     * @param gamepadBind the default gamepad bind
+     */
     ControllerBindingBuilder<T> defaultBind(GamepadBinds gamepadBind);
 
+    /**
+     * Sets the name of the binding.
+     * <p>
+     * If left unset, the default translation location is
+     * <p>
+     * {@code controlify.binding.<namespace>.<path>}.
+     *
+     * @param name the name of the binding
+     */
     ControllerBindingBuilder<T> name(Component name);
 
+    /**
+     * Sets the description of the binding.
+     * <p>
+     * If left unset, the default translation location is
+     * <p>
+     * {@code controlify.binding.<namespace>.<path>.desc}.
+     *
+     * @param description the description of the binding
+     */
     ControllerBindingBuilder<T> description(Component description);
 
+    /**
+     * Sets the category of the binding.
+     * Must be set.
+     *
+     * @param category the category of the binding
+     */
     ControllerBindingBuilder<T> category(Component category);
 
+    /**
+     * Specifies are vanilla override for the binding.
+     * Will emulate presses of the vanilla keybind when the controller binding is pressed.
+     * Though usage of this is discouraged as it can have funny behaviours.
+     *
+     * @param keyMapping the vanilla keybind to emulate
+     * @param toggleable if the binding should be toggleable
+     */
     ControllerBindingBuilder<T> vanillaOverride(KeyMapping keyMapping, BooleanSupplier toggleable);
 
+    /**
+     * Specifies are vanilla override for the binding.
+     * Will emulate presses of the vanilla keybind when the controller binding is pressed.
+     * Though usage of this is discouraged as it can have funny behaviours.
+     *
+     * @param keyMapping the vanilla keybind to emulate
+     */
     ControllerBindingBuilder<T> vanillaOverride(KeyMapping keyMapping);
 
     ControllerBinding<T> build();