Add further documentation to dialog API

dialog/src/main/java/net/md_5/bungee/api/dialog/DialogListDialog.java

@@ -35,7 +35,7 @@ public final class DialogListDialog implements Dialog
      */
     private int columns;
     /**
-     * The width of the dialog buttons (default: 150).
+     * The width of the dialog buttons (default: 150, minimum: 1, maximum: 1024).
      */
     @SerializedName("button_width")
     private int buttonWidth;

dialog/src/main/java/net/md_5/bungee/api/dialog/ServerLinksDialog.java

@@ -31,7 +31,7 @@ public final class ServerLinksDialog implements Dialog
      */
     private int columns;
     /**
-     * The width of the dialog buttons (default: 150).
+     * The width of the dialog buttons (default: 150, minimum: 1, maximum: 1024).
      */
     @SerializedName("button_width")
     private int buttonWidth;

dialog/src/main/java/net/md_5/bungee/api/dialog/action/DialogAction.java

@@ -21,7 +21,7 @@ public class DialogAction
      */
     private BaseComponent tooltip;
     /**
-     * The width of the button (default: 150).
+     * The width of the button (default: 150, minimum: 1, maximum: 1024).
      */
     private int width;
 

dialog/src/main/java/net/md_5/bungee/api/dialog/body/PlainMessageBody.java

@@ -20,7 +20,7 @@ public class PlainMessageBody extends DialogBody
      */
     private BaseComponent contents;
     /**
-     * The maximum width (default: 200).
+     * The maximum width (default: 200, minimum: 1, maximum: 1024).
      */
     private int width;
 

dialog/src/main/java/net/md_5/bungee/api/dialog/chat/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Contains dialog extensions to the chat API.
+ */
+package net.md_5.bungee.api.dialog.chat;

dialog/src/main/java/net/md_5/bungee/api/dialog/input/BooleanInput.java

@@ -7,6 +7,9 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
 
+/**
+ * Represents a checkbox input control.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -14,10 +17,22 @@ import net.md_5.bungee.api.chat.BaseComponent;
 public class BooleanInput extends DialogInput
 {
 
+    /**
+     * The input label.
+     */
     private BaseComponent label;
+    /**
+     * The initial value (default: false/unchecked).
+     */
     private boolean initial;
+    /**
+     * The string value to be submitted when true/checked (default: "true").
+     */
     @SerializedName("on_true")
     private String onTrue;
+    /**
+     * The string value to be submitted when false/unchecked (default: "false").
+     */
     @SerializedName("on_false")
     private String onFalse;
 

dialog/src/main/java/net/md_5/bungee/api/dialog/input/DialogInput.java

@@ -2,12 +2,25 @@ package net.md_5.bungee.api.dialog.input;
 
 import lombok.Data;
 import lombok.experimental.Accessors;
+import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * Represents a type of input which may be displayed/submitted with a form
+ * dialog.
+ */
 @Data
 @Accessors(fluent = true)
 public class DialogInput
 {
 
+    /**
+     * The internal input type.
+     */
+    @ApiStatus.Internal
     private final String type;
+    /**
+     * The key corresponding to this input and associated with the value
+     * submitted.
+     */
     private final String key;
 }

dialog/src/main/java/net/md_5/bungee/api/dialog/input/InputOption.java

@@ -5,14 +5,29 @@ import lombok.Data;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
 
+/**
+ * Represents an option choice which may form part of a
+ * {@link SingleOptionInput}.
+ */
 @Data
 @AllArgsConstructor
 @Accessors(fluent = true)
 public class InputOption
 {
 
+    /**
+     * The string value associated with this option, to be submitted when
+     * selected.
+     */
     private String id;
+    /**
+     * The text to display for this option.
+     */
     private BaseComponent display;
+    /**
+     * Whether this option is the one initially selected. Only one option may
+     * have this value as true (default: first option).
+     */
     private boolean initial;
 
     public InputOption(String id)

dialog/src/main/java/net/md_5/bungee/api/dialog/input/NumberRangeInput.java

@@ -6,6 +6,9 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
 
+/**
+ * Represents a number slider input.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -14,28 +17,33 @@ public class NumberRangeInput extends DialogInput
 {
 
     /**
-     * The width of the input (default 200)
+     * The width of the input (default: 200, minimum: 1, maximum: 1024).
      */
     private int width;
     /**
-     * The label of the slider
+     * The label of the slider.
      */
     private BaseComponent label;
+    /**
+     * A translate key used to display the label value (default:
+     * options.generic_value).
+     */
     private String labelFormat;
     /**
-     * The start position of the slider (leftmost position)
+     * The start position of the slider (leftmost position).
      */
     private float start;
     /**
-     * The end position of the slider (rightmost position)
+     * The end position of the slider (rightmost position).
      */
     private float end;
     /**
-     * The steps in which the input will be increased or decreased, or null if no specific steps
+     * The steps in which the input will be increased or decreased, or null if
+     * no specific steps.
      */
     private Float step;
     /**
-     * The initial value of number input, or null to fall back to the middle
+     * The initial value of number input, or null to fall back to the middle.
      */
     private Float initial;
 

dialog/src/main/java/net/md_5/bungee/api/dialog/input/SingleOptionInput.java

@@ -1,5 +1,6 @@
 package net.md_5.bungee.api.dialog.input;
 
+import com.google.common.base.Preconditions;
 import com.google.gson.annotations.SerializedName;
 import java.util.Arrays;
 import java.util.List;
@@ -9,6 +10,9 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
 
+/**
+ * Represents a single option (dropdown) input.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -16,10 +20,22 @@ import net.md_5.bungee.api.chat.BaseComponent;
 public class SingleOptionInput extends DialogInput
 {
 
+    /**
+     * The width of the input (default: 200, minimum: 1, maximum: 1024).
+     */
     private int width;
+    /**
+     * The input label.
+     */
     private BaseComponent label;
+    /**
+     * Whether the label is visible (default: true).
+     */
     @SerializedName("label_visible")
     private boolean labelVisible;
+    /**
+     * The non-empty list of options to be selected from.
+     */
     private List<InputOption> options;
 
     public SingleOptionInput(String key, BaseComponent label, InputOption... options)
@@ -30,6 +46,8 @@ public class SingleOptionInput extends DialogInput
     public SingleOptionInput(String key, int width, BaseComponent label, boolean labelVisible, List<InputOption> options)
     {
         super( "minecraft:single_option", key );
+        Preconditions.checkArgument( options != null && !options.isEmpty(), "At least one option must be provided" );
+
         this.width = width;
         this.label = label;
         this.labelVisible = labelVisible;

dialog/src/main/java/net/md_5/bungee/api/dialog/input/TextInput.java

@@ -7,6 +7,9 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
 
+/**
+ * Represents a textbox input.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -15,26 +18,29 @@ public class TextInput extends DialogInput
 {
 
     /**
-     * The width of this text input
+     * The width of this text input (default: 200, minimum: 1, maximum: 1024).
      */
     private int width;
     /**
-     * The label of this text input
+     * The label of this text input.
      */
     private BaseComponent label;
     /**
-     * The visibility of this text inputs label
+     * The visibility of this text input's label.
      */
     @SerializedName("label_visible")
     private boolean labelVisible;
     /**
-     * The initial value of this text input
+     * The initial value of this text input.
      */
     private String initial;
+    /**
+     * The maximum length of the input (default: 32).
+     */
     @SerializedName("max_length")
     private int maxLength;
     /**
-     * if set, allows users to input multiple lines
+     * If present, allows users to input multiple lines.
      */
     private Multiline multiline;
 
@@ -59,19 +65,21 @@ public class TextInput extends DialogInput
         this.multiline = multiline;
     }
 
+    /**
+     * Configuration data for a multiline input.
+     */
     @Data
     @Accessors(fluent = true)
-    @ToString(callSuper = true)
-    @EqualsAndHashCode(callSuper = false)
     public static class Multiline
     {
+
         /**
-         * The maximum length of input, or null to disable any limits
+         * The maximum length of input, or null to disable any limits.
          */
         @SerializedName("max_lines")
         private Integer maxLines;
         /**
-         * The height of this input, default value is 32
+         * The height of this input (default: 32, minimum: 1, maximum: 512).
          */
         private Integer height = 32;
     }

dialog/src/main/java/net/md_5/bungee/api/dialog/input/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Represents the various input controls which may be present on form dialogs.
+ */
+package net.md_5.bungee.api.dialog.input;

dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CommandTemplateSubmission.java

@@ -5,6 +5,10 @@ import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import lombok.experimental.Accessors;
 
+/**
+ * Executes a command on form submission. If the command requires a permission
+ * higher than 0, a confirmation dialog will be shown by the client.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -12,6 +16,14 @@ import lombok.experimental.Accessors;
 public class CommandTemplateSubmission extends DialogSubmission
 {
 
+    /**
+     * The template to be applied, where variables of the form
+     * <code>$(key)</code> will be replaced by their
+     * {@link net.md_5.bungee.api.dialog.input.DialogInput#key} value.
+     * <br>
+     * The <code>action</code> key is special and will be replaced with the
+     * {@link net.md_5.bungee.api.dialog.action.DialogSubmitAction#id}.
+     */
     private String template;
 
     public CommandTemplateSubmission(String template)

dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomFormSubmission.java

@@ -5,6 +5,9 @@ import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import lombok.experimental.Accessors;
 
+/**
+ * Submits the form with the given ID and all values as a payload.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -12,6 +15,9 @@ import lombok.experimental.Accessors;
 public class CustomFormSubmission extends DialogSubmission
 {
 
+    /**
+     * The namespaced key of the submission.
+     */
     private String id;
 
     public CustomFormSubmission(String id)

dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomTemplateSubmission.java

@@ -5,6 +5,10 @@ import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import lombok.experimental.Accessors;
 
+/**
+ * Submits the form with the given ID and a single payload specified by the
+ * template.
+ */
 @Data
 @Accessors(fluent = true)
 @ToString(callSuper = true)
@@ -12,7 +16,18 @@ import lombok.experimental.Accessors;
 public class CustomTemplateSubmission extends DialogSubmission
 {
 
+    /**
+     * The namespaced key of the submission.
+     */
     private String id;
+    /**
+     * The template to be applied, where variables of the form
+     * <code>$(key)</code> will be replaced by their
+     * {@link net.md_5.bungee.api.dialog.input.DialogInput#key} value.
+     * <br>
+     * The <code>action</code> key is special and will be replaced with the
+     * {@link net.md_5.bungee.api.dialog.action.DialogSubmitAction#id}.
+     */
     private String template;
 
     public CustomTemplateSubmission(String id, String template)

dialog/src/main/java/net/md_5/bungee/api/dialog/submit/DialogSubmission.java

@@ -2,11 +2,19 @@ package net.md_5.bungee.api.dialog.submit;
 
 import lombok.Data;
 import lombok.experimental.Accessors;
+import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * Represents an action which may be taken on form dialog submission.
+ */
 @Data
 @Accessors(fluent = true)
 public class DialogSubmission
 {
 
+    /**
+     * The internal submissions type.
+     */
+    @ApiStatus.Internal
     private final String type;
 }

dialog/src/main/java/net/md_5/bungee/api/dialog/submit/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Represents the various submissions actions of form dialogs.
+ */
+package net.md_5.bungee.api.dialog.submit;