Document package net.md_5.bungee.api.dialog

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

@@ -7,17 +7,27 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.dialog.action.DialogClickAction;
 
+/**
+ * Represents a simple dialog with text and two actions at the bottom (default:
+ * "yes", "no").
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @AllArgsConstructor
 @Accessors(fluent = true)
-public class ConfirmationDialog implements Dialog
+public final class ConfirmationDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The "yes" click action / bottom (appears on the left).
+     */
     private DialogClickAction yes;
+    /**
+     * The "no" click action / bottom (appears on the right).
+     */
     private DialogClickAction no;
 
     public ConfirmationDialog(DialogBase base)

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

@@ -1,9 +1,29 @@
 package net.md_5.bungee.api.dialog;
 
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Represents a dialog GUI.
+ */
 public interface Dialog
 {
 
+    /**
+     * Gets the dialog base which contains the dialog title and other options
+     * common to all types of dialogs.
+     *
+     * @return mutable reference to the dialog base
+     */
     DialogBase getBase();
 
+    /**
+     * Sets the dialog base.
+     * <br>
+     * For internal use only as this is mandatory and should be specified in the
+     * constructor.
+     *
+     * @param base the new dialog base
+     */
+    @ApiStatus.Internal
     void setBase(DialogBase base);
 }

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

@@ -6,16 +6,33 @@ import lombok.Data;
 import lombok.RequiredArgsConstructor;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.BaseComponent;
+import net.md_5.bungee.api.dialog.body.DialogBody;
 
+/**
+ * Represents the title and other options common to all dialogs.
+ */
 @Data
 @AllArgsConstructor
 @RequiredArgsConstructor
 @Accessors(fluent = true)
-public class DialogBase
+public final class DialogBase
 {
 
+    /**
+     * The mandatory dialog title.
+     */
     private final BaseComponent title;
+    /**
+     * The name which is used for any buttons leading to this dialog (eg from a
+     * {@link DialogListDialog}). Otherwise defaults to {@link #title}.
+     */
     private BaseComponent externalTitle;
-    private List<?> body;
+    /**
+     * The body elements which make up this dialog.
+     */
+    private List<DialogBody> body;
+    /**
+     * Whether this dialog can be closed with the escape key (default: true).
+     */
     private boolean canCloseWithEscape;
 }

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

@@ -9,19 +9,34 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.ClickEvent;
 
+/**
+ * Represents a dialog which contains buttons that link to other dialogs.
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @Accessors(fluent = true)
-public class DialogListDialog implements Dialog
+public final class DialogListDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The child dialogs behind each button.
+     */
     private List<Dialog> dialogs;
+    /**
+     * The {@link ClickEvent} activated when the dialog is cancelled.
+     */
     @SerializedName("on_cancel")
     private ClickEvent onCancel;
+    /**
+     * The number of columns for the dialog buttons (default: 2).
+     */
     private int columns;
+    /**
+     * The width of the dialog buttons (default: 150).
+     */
     @SerializedName("button_width")
     private int buttonWidth;
 

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

@@ -11,17 +11,30 @@ import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.ClickEvent;
 import net.md_5.bungee.api.dialog.action.DialogClickAction;
 
+/**
+ * Represents a dialog with text a list of action buttons grouped into columns
+ * and scrollable if necessary.
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @Accessors(fluent = true)
-public class MultiActionDialog implements Dialog
+public final class MultiActionDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The action buttons in the dialog. At least one must be provided.
+     */
     private List<DialogClickAction> actions;
+    /**
+     * The number of columns for the dialog buttons (default: 2).
+     */
     private int columns;
+    /**
+     * The {@link ClickEvent} activated when the dialog is cancelled.
+     */
     @SerializedName("on_cancel")
     private ClickEvent onCancel;
 

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

@@ -1,29 +1,50 @@
 package net.md_5.bungee.api.dialog;
 
+import com.google.common.base.Preconditions;
+import java.util.Arrays;
 import java.util.List;
-import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import lombok.experimental.Accessors;
-import net.md_5.bungee.api.dialog.action.DialogClickAction;
+import net.md_5.bungee.api.dialog.action.DialogSubmitAction;
 import net.md_5.bungee.api.dialog.input.DialogInput;
 
+/**
+ * Represents a dialog which contains a variety of inputs and a multiple submit
+ * buttons at the bottom.
+ */
 @Data
 @ToString
 @EqualsAndHashCode
-@AllArgsConstructor
 @Accessors(fluent = true)
-public class MultiActionInputFormDialog implements Dialog
+public final class MultiActionInputFormDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The inputs to the dialog. At least one input must be provided.
+     */
     private List<DialogInput> inputs;
-    private List<DialogClickAction> actions;
+    /**
+     * The action/submit buttons for the dialog. At least one action must be
+     * provided.
+     */
+    private List<DialogSubmitAction> actions;
 
-    public MultiActionInputFormDialog(DialogBase base)
+    public MultiActionInputFormDialog(DialogBase base, DialogInput input, DialogSubmitAction action)
     {
-        this( base, null, null );
+        this( base, Arrays.asList( input ), Arrays.asList( action ) );
+    }
+
+    public MultiActionInputFormDialog(DialogBase base, List<DialogInput> inputs, List<DialogSubmitAction> actions)
+    {
+        Preconditions.checkArgument( inputs != null && !inputs.isEmpty(), "At least one input must be provided" );
+        Preconditions.checkArgument( actions != null && !actions.isEmpty(), "At least one action must be provided" );
+
+        this.base = base;
+        this.inputs = inputs;
+        this.actions = actions;
     }
 }

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

@@ -7,16 +7,23 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.dialog.action.DialogClickAction;
 
+/**
+ * Represents a simple dialog with text and one action at the bottom (default:
+ * "OK").
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @AllArgsConstructor
 @Accessors(fluent = true)
-public class NoticeDialog implements Dialog
+public final class NoticeDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The "OK" action button for the dialog.
+     */
     private DialogClickAction action;
 
     public NoticeDialog(DialogBase base)

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

@@ -8,19 +8,31 @@ import lombok.ToString;
 import lombok.experimental.Accessors;
 import net.md_5.bungee.api.chat.ClickEvent;
 
+/**
+ * Represents a dialog which shows the links configured/sent from the server.
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @AllArgsConstructor
 @Accessors(fluent = true)
-public class ServerLinksDialog implements Dialog
+public final class ServerLinksDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The optional {@link ClickEvent} for this dialog.
+     */
     @SerializedName("on_click")
     private ClickEvent onClick;
+    /**
+     * The number of columns for the dialog buttons (default: 2).
+     */
     private int columns;
+    /**
+     * The width of the dialog buttons (default: 150).
+     */
     @SerializedName("button_width")
     private int buttonWidth;
 

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

@@ -1,5 +1,6 @@
 package net.md_5.bungee.api.dialog;
 
+import com.google.common.base.Preconditions;
 import java.util.Arrays;
 import java.util.List;
 import lombok.Data;
@@ -9,16 +10,26 @@ import lombok.experimental.Accessors;
 import net.md_5.bungee.api.dialog.action.DialogSubmitAction;
 import net.md_5.bungee.api.dialog.input.DialogInput;
 
+/**
+ * Represents a dialog which contains a variety of inputs and a single submit
+ * button at the bottom.
+ */
 @Data
 @ToString
 @EqualsAndHashCode
 @Accessors(fluent = true)
-public class SimpleInputFormDialog implements Dialog
+public final class SimpleInputFormDialog implements Dialog
 {
 
     @Accessors(fluent = false)
     private DialogBase base;
+    /**
+     * The inputs to the dialog. At least one input must be provided.
+     */
     private List<DialogInput> inputs;
+    /**
+     * The action/submit buttons for the dialog.
+     */
     private DialogSubmitAction action;
 
     public SimpleInputFormDialog(DialogBase base, DialogInput... inputs)
@@ -33,6 +44,8 @@ public class SimpleInputFormDialog implements Dialog
 
     public SimpleInputFormDialog(DialogBase base, DialogSubmitAction action, List<DialogInput> inputs)
     {
+        Preconditions.checkArgument( inputs != null && !inputs.isEmpty(), "At least one input must be provided" );
+
         this.base = base;
         this.inputs = inputs;
         this.action = action;

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

@@ -3,7 +3,7 @@ package net.md_5.bungee.api.dialog.body;
 import lombok.Data;
 
 @Data
-public class DialogBody
+public abstract class DialogBody
 {
 
     private final String type;

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

@@ -0,0 +1,4 @@
+/**
+ * Contains the core classes for the display of a {@link Dialog}.
+ */
+package net.md_5.bungee.api.dialog;