Update documentation, refactor class/package locations

SamJakob · SamJakob · commit 6ce4313bc606 · 2023-03-21T23:54:27.000Z
diff --git a/build.gradle b/build.gradle
@@ -10,6 +10,9 @@ uri "https://github.com/SamJakob/SpiGUI"
 java {
     sourceCompatibility = 1.8
     targetCompatibility = 1.8
+
+    withJavadocJar()
+    withSourcesJar()
 }
 
 repositories {
@@ -33,6 +36,8 @@ dependencies {
     implementation group: 'org.spigotmc', name: 'spigot-api', version: '1.8.8-R0.1-SNAPSHOT'
 }
 
+// Builds Spigot runnable plugin from the test package.
+// Can be used to demonstrate and test functionality.
 tasks.register('testJar', Jar) {
     from sourceSets.main.output.classesDirs
     from sourceSets.test.output.classesDirs
@@ -43,41 +48,21 @@ tasks.register('testJar', Jar) {
     archiveBaseName.set("SpiGUITest")
 }
 
-tasks.register('sourcesJar', Jar) {
-    archiveClassifier.set('sources')
-    from sourceSets.main.java.sourceDirectories
-}
-
-tasks.register('classesJar', Jar) {
-    from sourceSets.main.output.classesDirs
-}
+javadoc {
+    if (JavaVersion.current().isJava9Compatible()) {
+        options.addBooleanOption('html5', true);
+    }
 
-tasks.register('documentation', Javadoc) {
     source = sourceSets.main.java.sourceDirectories
     classpath += configurations.compileClasspath
 
     options.memberLevel = JavadocMemberLevel.PRIVATE
 }
 
-tasks.register('javadocJar', Jar) {
-    dependsOn documentation
-    archiveClassifier.set('javadoc')
-    from documentation.destinationDir
-}
-
-artifacts {
-    archives classesJar
-    archives javadocJar
-    archives sourcesJar
-}
-
 publishing {
     publications {
         SpiGUI(MavenPublication) {
             from components.java
-
-            artifact(javadocJar)
-            artifact(sourcesJar)
         }
     }
 }
diff --git a/src/main/java/com/samjakob/spigui/SpiGUI.java b/src/main/java/com/samjakob/spigui/SpiGUI.java
@@ -1,10 +1,11 @@
 package com.samjakob.spigui;
 
 import com.samjakob.spigui.buttons.SGButton;
+import com.samjakob.spigui.menu.SGMenu;
 import com.samjakob.spigui.menu.SGMenuListener;
 import com.samjakob.spigui.menu.SGOpenMenu;
 import com.samjakob.spigui.item.ItemBuilder;
-import com.samjakob.spigui.pagination.SGToolbarBuilder;
+import com.samjakob.spigui.toolbar.SGToolbarBuilder;
 import org.bukkit.Material;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.Inventory;
@@ -14,11 +15,13 @@
 import java.util.List;
 
 /**
- * A comprehensive GUI API for Spigot with pages support.<br>
- * <a href="https://github.com/SamJakob/SpiGUI">https://github.com/SamJakob/SpiGUI</a>
- *
- * @author SamJakob
- * @version 1.3.0
+ * The core class for the SpiGUI library.<br>
+ * One instance of the SpiGUI class is registered for each plugin using it.
+ * <p>
+ * The expected usage of SpiGUI is that you register a SpiGUI instance for your
+ * plugin with <code>new SpiGUI(this);</code> in your class that extends
+ * <code>JavaPlugin</code>. You can then use the instance you've created throughout
+ * your project to create GUIs that use SpiGUI.
  */
 public class SpiGUI {
 
diff --git a/src/main/java/com/samjakob/spigui/buttons/package-info.java b/src/main/java/com/samjakob/spigui/buttons/package-info.java
@@ -0,0 +1,8 @@
+/**
+ * Clickable elements for SpiGUI menus ({@link com.samjakob.spigui.menu.SGMenu}).<br>
+ * Presently, only a button is implemented: {@link com.samjakob.spigui.buttons.SGButton}.
+ *
+ * @since 1.0.0
+ * @version 1.3.0
+ */
+package com.samjakob.spigui.buttons;
diff --git a/src/main/java/com/samjakob/spigui/item/package-info.java b/src/main/java/com/samjakob/spigui/item/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * The {@link com.samjakob.spigui.item.ItemBuilder} API (and friends).<br>
+ * This holds the ItemBuilder API class and other classes (or enums) used to implement it.
+ */
+package com.samjakob.spigui.item;
diff --git a/src/main/java/com/samjakob/spigui/menu/SGMenu.java b/src/main/java/com/samjakob/spigui/menu/SGMenu.java
@@ -1,8 +1,9 @@
-package com.samjakob.spigui;
+package com.samjakob.spigui.menu;
 
+import com.samjakob.spigui.SpiGUI;
 import com.samjakob.spigui.buttons.SGButton;
-import com.samjakob.spigui.pagination.SGToolbarBuilder;
-import com.samjakob.spigui.pagination.SGToolbarButtonType;
+import com.samjakob.spigui.toolbar.SGToolbarBuilder;
+import com.samjakob.spigui.toolbar.SGToolbarButtonType;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.entity.HumanEntity;
@@ -50,16 +51,21 @@ public class SGMenu implements InventoryHolder {
     private Consumer<SGMenu> onPageChange;
 
     /**
+     * <b>Intended for internal use only. Use {@link SpiGUI#create(String, int)} or {@link SpiGUI#create(String, int, String)}!</b><br>
      * Used by the library internally to construct an SGMenu.
+     * <p>
      * The name parameter is color code translated.
      *
      * @param owner The plugin the inventory should be associated with.
      * @param spiGUI The SpiGUI that created this inventory.
      * @param name The display name of the inventory.
      * @param rowsPerPage The number of rows per page.
      * @param tag The inventory's tag.
+     *            
+     * @see SpiGUI#create(String, int)
+     * @see SpiGUI#create(String, int, String) 
      */
-    SGMenu(JavaPlugin owner, SpiGUI spiGUI, String name, int rowsPerPage, String tag) {
+    public SGMenu(JavaPlugin owner, SpiGUI spiGUI, String name, int rowsPerPage, String tag) {
         this.owner = owner;
         this.spiGUI = spiGUI;
         this.name = ChatColor.translateAlternateColorCodes('&', name);
diff --git a/src/main/java/com/samjakob/spigui/menu/SGMenuListener.java b/src/main/java/com/samjakob/spigui/menu/SGMenuListener.java
@@ -1,10 +1,9 @@
 package com.samjakob.spigui.menu;
 
-import com.samjakob.spigui.SGMenu;
 import com.samjakob.spigui.SpiGUI;
 import com.samjakob.spigui.buttons.SGButton;
-import com.samjakob.spigui.pagination.SGToolbarBuilder;
-import com.samjakob.spigui.pagination.SGToolbarButtonType;
+import com.samjakob.spigui.toolbar.SGToolbarBuilder;
+import com.samjakob.spigui.toolbar.SGToolbarButtonType;
 import org.bukkit.event.EventHandler;
 import org.bukkit.event.EventPriority;
 import org.bukkit.event.Listener;
diff --git a/src/main/java/com/samjakob/spigui/menu/SGOpenMenu.java b/src/main/java/com/samjakob/spigui/menu/SGOpenMenu.java
@@ -1,8 +1,10 @@
 package com.samjakob.spigui.menu;
 
-import com.samjakob.spigui.SGMenu;
 import org.bukkit.entity.Player;
 
+/**
+ * Used to refer to an open menu.
+ */
 public class SGOpenMenu {
 
     private final SGMenu gui;
@@ -13,10 +15,18 @@ public SGOpenMenu(SGMenu gui, Player player) {
         this.player = player;
     }
 
-    public SGMenu getGUI() {
+    /**
+     * Get the open {@link SGMenu} instance.
+     * @return The menu that is open.
+     */
+    public SGMenu getMenu() {
         return this.gui;
     }
 
+    /**
+     * Get the player viewing the {@link SGMenu}.
+     * @return The player viewing the menu.
+     */
     public Player getPlayer() {
         return this.player;
     }
diff --git a/src/main/java/com/samjakob/spigui/menu/package-info.java b/src/main/java/com/samjakob/spigui/menu/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Menu definitions, including the listener (which handles user events).<br>
+ * See: {@link com.samjakob.spigui.menu.SGMenu}.
+ */
+package com.samjakob.spigui.menu;
diff --git a/src/main/java/com/samjakob/spigui/toolbar/SGToolbarBuilder.java b/src/main/java/com/samjakob/spigui/toolbar/SGToolbarBuilder.java
@@ -1,6 +1,6 @@
-package com.samjakob.spigui.pagination;
+package com.samjakob.spigui.toolbar;
 
-import com.samjakob.spigui.SGMenu;
+import com.samjakob.spigui.menu.SGMenu;
 import com.samjakob.spigui.buttons.SGButton;
 
 public interface SGToolbarBuilder {
diff --git a/src/main/java/com/samjakob/spigui/toolbar/SGToolbarButtonType.java b/src/main/java/com/samjakob/spigui/toolbar/SGToolbarButtonType.java
@@ -1,4 +1,4 @@
-package com.samjakob.spigui.pagination;
+package com.samjakob.spigui.toolbar;
 
 import java.util.AbstractMap;
 import java.util.Map;
diff --git a/src/main/java/com/samjakob/spigui/toolbar/package-info.java b/src/main/java/com/samjakob/spigui/toolbar/package-info.java
@@ -0,0 +1,12 @@
+/**
+ * The Toolbar API.<br>
+ * Used to override the pagination buttons, or to add fixed toolbar items.
+ * <p>
+ * This contains the {@link com.samjakob.spigui.toolbar.SGToolbarBuilder} interface,
+ * responsible for delegating the building of each toolbar button.
+ * <p>
+ * For usage,
+ * see {@link com.samjakob.spigui.menu.SGMenu#setToolbarBuilder(com.samjakob.spigui.toolbar.SGToolbarBuilder)}
+ * or {@link com.samjakob.spigui.SpiGUI#setDefaultToolbarBuilder(com.samjakob.spigui.toolbar.SGToolbarBuilder)}.
+ */
+package com.samjakob.spigui.toolbar;
diff --git a/src/main/java/package-info.java b/src/main/java/package-info.java
@@ -0,0 +1,8 @@
+/**
+ * A comprehensive GUI API for Spigot with pages support.<br>
+ * <a href="https://github.com/SamJakob/SpiGUI">https://github.com/SamJakob/SpiGUI</a>
+ *
+ * @since 1.0.0
+ * @version 1.3.0
+ */
+package com.samjakob.spigui;
diff --git a/src/test/java/com/samjakob/spiguitest/SpiGUITest.java b/src/test/java/com/samjakob/spiguitest/SpiGUITest.java
@@ -1,6 +1,6 @@
 package com.samjakob.spiguitest;
 
-import com.samjakob.spigui.SGMenu;
+import com.samjakob.spigui.menu.SGMenu;
 import com.samjakob.spigui.SpiGUI;
 import com.samjakob.spigui.buttons.SGButton;
 import com.samjakob.spigui.item.ItemBuilder;
@@ -16,11 +16,9 @@
 import org.bukkit.scheduler.BukkitRunnable;
 import org.bukkit.scheduler.BukkitTask;
 
-import java.time.Duration;
 import java.util.*;
 import java.util.concurrent.ThreadLocalRandom;
 import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package com.samjakob.spigui.pagination;`
	`1`	`+package com.samjakob.spigui.toolbar;`
`2`	`2`
`3`	`3`	`import java.util.AbstractMap;`
`4`	`4`	`import java.util.Map;`