Update docs, simplify MenuManager and remove its generics (#18)

* refactor(menus): move MenuManager out of its own package

It's redundant for now to have a package for a single class.
This is a breaking change.

* fix(menus): remove generics from MenuManager

It's hard to figure out how those generics should even be used, and they're preventing parameterized MenuManager instances from being compiled successfully when used in AbstractMenu.open methods.

* feat(github): add library installation guide to README.md

* fix(ci/cd): use groovy language in release draft Gradle code block

* docs(github,maven): upgrade library version

Author: CosimoTiger

.github/workflows/release-drafter.yml

@@ -65,7 +65,7 @@ jobs:
             
             #### Gradle
             
-            ```gradle
+            ```groovy
             dependencyResolutionManagement {
               repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
               repositories {

README.md

@@ -4,11 +4,10 @@ A library with some common utilities for ease of developing Spigot plugins.
 
 # Features
 
-- menu library for custom menus and handling of all their events
+- central menu module for custom menus and handling of all their events
 - `ItemBuilder` for less headache with `ItemMeta` and `ItemStack` modifications
 - cooldowns that manage themselves
 - plugin file handling
-- miscellaneous utilities
 
 ## The menu library
 
@@ -19,10 +18,102 @@ overriden by the developer; it also comes with some pre-made classes that can be
 
 To use the library, a `MenuManager` needs to be instantiated, which will manage all the menus that are passed to it.
 
-## How to use `plugin-utilities` (WIP)
+## How to use `plugin-utilities`
 
-1. Add the library as a JitPack dependency via a build automation that you're using, such as Maven, Gradle, Ant, etc.
-2. Shade the dependency, possibly with the JAR minimization option to exclude the utilities you're not using, which will
-   lower the file size impact of the dependency even though it's currently rather small.
-3. Write your code. The menu library, for example, requires you to instantiate a `MenuManager` with your `Plugin`
-   instance to use it.
+1. Add the library as a JitPack dependency via a build automation tool that you're using, such as Maven, Gradle, Ant,
+   etc.
+
+    ```xml
+   <project>
+        <repositories>
+            <repository>
+                <id>jitpack.io</id>
+                <url>https://jitpack.io</url>
+            </repository>
+        </repositories>
+        
+       <dependencies>
+            <dependency>
+               <groupId>com.github.CosimoTiger</groupId>
+               <artifactId>plugin-utilities</artifactId>
+               <version>1.0.0-alpha.2</version>
+            </dependency>
+       </dependencies>
+   </project>
+    ```
+
+    ```groovy
+    dependencyResolutionManagement {
+        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+        repositories {
+            mavenCentral()
+            maven { url 'https://jitpack.io' }
+        }
+    }
+    
+    dependencies {
+        implementation 'com.github.CosimoTiger:plugin-utilities:1.0.0-alpha.2'
+    }
+    ```
+
+2. **Optional step:** you can shade the dependency library using JAR minimization to exclude unused features from being
+   compiled with your plugin, which will decrease the file size impact of the dependency even though it's currently very
+   small and lightweight. Here's one way of doing it:
+
+   Inside `<plugins>...</plugins>` add:
+
+    ```xml
+    <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-shade-plugin</artifactId>
+        <version>3.6.0</version>
+        <executions>
+            <execution>
+                <phase>package</phase>
+                <goals>
+                    <goal>shade</goal>
+                </goals>
+                <configuration>
+                    <minimizeJar>true</minimizeJar>
+                </configuration>
+            </execution>
+        </executions>
+    </plugin>
+    ```
+
+   Beware of what these options do – if you're using Java Reflection, databases or possibly dependency injection, those
+   dependencies may be affected, but don't fret because you
+   can [exclude them from the process](https://maven.apache.org/plugins/maven-shade-plugin/examples/includes-excludes.html).
+
+3. Start writing your code. Here's the typical plugin initialization code example:
+
+    ```java
+    import com.cosimo.utilities.file.YamlFile;
+    import com.cosimo.utilities.menu.AbstractMenu;
+    import com.cosimo.utilities.menu.manager.MenuManager;
+    import org.bukkit.plugin.java.JavaPlugin;
+    
+    public class ExamplePlugin extends JavaPlugin {
+    
+       private static MenuManager menuManager = null;
+       private static ExamplePlugin instance = null;
+    
+       @Override
+       public void onEnable() {
+          menuManager = new MenuManager(this);
+          instance = this;
+    
+          final var config = new YamlFile(this, "config.yml").reloadFile().getMemory();
+    
+          getCommand("example").setExecutor(new ExampleCommand(config.getConfigurationSection("commands.example")));
+       }
+    
+       public static MenuManager getMenuManager() {
+          return menuManager;
+       }
+    
+       public static ExamplePlugin getInstance() {
+          return instance;
+       }
+    }
+    ```

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.cosimo</groupId>
     <artifactId>plugin-utilities</artifactId>
-    <version>1.0.0-alpha.1</version>
+    <version>1.0.0-alpha.2</version>
     <name>PluginUtilities</name>
     <url>https://github.com/CosimoTiger/plugin-utilities</url>
     <description>A library with many utilities that help with developing Spigot plugins.</description>

src/main/java/com/cosimo/utilities/menu/AbstractMenu.java

@@ -1,6 +1,5 @@
 package com.cosimo.utilities.menu;
 
-import com.cosimo.utilities.menu.manager.MenuManager;
 import com.cosimo.utilities.menu.type.Menu;
 import com.cosimo.utilities.menu.type.PropertyMenu;
 import com.google.common.base.Preconditions;
@@ -98,7 +97,7 @@ public void onOpen(@NonNull InventoryOpenEvent event) {
      * @throws NullPointerException     If a {@link HumanEntity} is null
      */
     @NonNull
-    public Self open(@NonNull MenuManager<AbstractMenu<?>> menuManager,
+    public Self open(@NonNull MenuManager menuManager,
                      @NonNull Iterable<@NonNull ? extends HumanEntity> viewers) {
         menuManager.registerMenu(this);
 
@@ -127,7 +126,7 @@ public Self open(@NonNull MenuManager<AbstractMenu<?>> menuManager,
      * @throws NullPointerException     If a {@link HumanEntity} is null
      */
     @NonNull
-    public Self open(@NonNull MenuManager<AbstractMenu<?>> menuManager, @NonNull HumanEntity @NonNull ... viewers) {
+    public Self open(@NonNull MenuManager menuManager, @NonNull HumanEntity @NonNull ... viewers) {
         return this.open(menuManager, List.of(viewers));
     }
 

src/main/java/com/cosimo/utilities/menu/IMenu.java

@@ -1,6 +1,5 @@
 package com.cosimo.utilities.menu;
 
-import com.cosimo.utilities.menu.manager.MenuManager;
 import lombok.NonNull;
 import org.bukkit.entity.HumanEntity;
 import org.bukkit.event.inventory.InventoryAction;

src/main/java/com/cosimo/utilities/menu/InventoryListener.java

@@ -16,8 +16,7 @@ public interface InventoryListener {
      * such.
      *
      * @param event    {@link InventoryClickEvent}
-     * @param external Whether the clicked slot is outside the inventory menu detected by
-     *                 {@link com.cosimo.utilities.menu.manager.MenuManager}
+     * @param external Whether the clicked slot is outside the inventory menu detected by {@link MenuManager}
      */
     void onClick(@NonNull InventoryClickEvent event, boolean external);
 

…/utilities/menu/manager/MenuManager.java …m/cosimo/utilities/menu/MenuManager.javasrc/main/java/com/cosimo/utilities/menu/manager/MenuManager.java renamed to src/main/java/com/cosimo/utilities/menu/MenuManager.java src/main/java/com/cosimo/utilities/menu/manager/MenuManager.java renamed to src/main/java/com/cosimo/utilities/menu/MenuManager.java

@@ -1,6 +1,5 @@
-package com.cosimo.utilities.menu.manager;
+package com.cosimo.utilities.menu;
 
-import com.cosimo.utilities.menu.IMenu;
 import com.google.common.base.Preconditions;
 import lombok.NonNull;
 import org.bukkit.Bukkit;
@@ -24,9 +23,10 @@
 import java.util.logging.Level;
 
 /**
- * A {@link Listener} that filters {@link org.bukkit.event.inventory.InventoryEvent}s to registered {@link Inventory}
- * {@link IMenu}s. Menu inventory listening is delegated and centralised in one {@link MenuManager} because of the
- * assumption that constantly registering and unregistering new {@link Listener}s for each {@link IMenu} is slow.
+ * A {@link Listener} that filters and dispatches {@link org.bukkit.event.inventory.InventoryEvent}s to registered
+ * {@link Inventory} {@link IMenu}s. Menu inventory listening is delegated and centralised in one {@link MenuManager}
+ * because of the assumption that constantly registering and unregistering new {@link Listener}s for each {@link IMenu}
+ * is slow.
  *
  * <p><strong>Note:</strong> {@link IMenu}s should be unregistered from their {@link MenuManager} when they're
  * not in use anymore, such as when the last viewer closes an {@link IMenu}. The unfollowing of this rule will cause a
@@ -35,18 +35,16 @@
  * <p><strong>Warning:</strong> {@link IMenu}s in multiple {@link MenuManager} instances may cause
  * duplicate event handler calls.
  *
- * @param <E> {@link IMenu} subclass restriction that's always expected to be received or added to this
- *            {@link MenuManager}
  * @author CosimoTiger
  */
-public class MenuManager<E extends IMenu> implements Listener {
+public class MenuManager implements Listener {
 
     // TODO: WeakHashMap? Inventories might be referenced only by their Bukkit viewers.
     //  WeakHashMap<Inventory, WeakReference<IMenu>> = new WeakHashMap<>(4);
     /**
      * Stores {@link IMenu} associations to their {@link Inventory} instances for quick access.
      */
-    private final Map<Inventory, E> menus;
+    private final Map<Inventory, IMenu> menus;
     private final Plugin provider;
 
     /**
@@ -57,7 +55,7 @@ public class MenuManager<E extends IMenu> implements Listener {
      * @throws IllegalArgumentException If the {@link Plugin} argument is null
      * @throws IllegalStateException    If the {@link Plugin} argument is not enabled
      */
-    protected MenuManager(@NonNull Plugin provider, @NonNull Map<Inventory, E> mapImpl) {
+    protected MenuManager(@NonNull Plugin provider, @NonNull Map<Inventory, IMenu> mapImpl) {
         Preconditions.checkState(provider.isEnabled(), "Plugin provider argument can't be disabled");
         Bukkit.getPluginManager().registerEvents(this, this.provider = provider);
         this.menus = mapImpl;
@@ -82,7 +80,7 @@ public MenuManager(@NonNull Plugin provider) {
      * @throws IllegalArgumentException If the {@link Inventory} argument is null
      */
     @NonNull
-    public Optional<E> unregisterMenu(@NonNull Inventory inventory) {
+    public Optional<IMenu> unregisterMenu(@NonNull Inventory inventory) {
         return Optional.ofNullable(this.menus.remove(inventory));
     }
 
@@ -94,7 +92,7 @@ public Optional<E> unregisterMenu(@NonNull Inventory inventory) {
      * @throws IllegalArgumentException If the {@link IMenu} argument is null
      */
     @NonNull
-    public Optional<E> unregisterMenu(@NonNull E menu) {
+    public Optional<IMenu> unregisterMenu(@NonNull IMenu menu) {
         return Optional.ofNullable(this.menus.remove(menu.getInventory()));
     }
 
@@ -107,7 +105,7 @@ public Optional<E> unregisterMenu(@NonNull E menu) {
      * @throws IllegalArgumentException If the {@link IMenu} argument is null
      */
     @NonNull
-    public Optional<E> registerMenu(@NonNull E menu) {
+    public Optional<IMenu> registerMenu(@NonNull IMenu menu) {
         return Optional.ofNullable(this.menus.put(menu.getInventory(), menu));
     }
 
@@ -120,7 +118,7 @@ public Optional<E> registerMenu(@NonNull E menu) {
      * @return This instance, useful for chaining
      */
     @NonNull
-    public MenuManager<E> closeMenus() {
+    public MenuManager closeMenus() {
         /*
          * Closing each menu calls an InventoryCloseEvent which may unregister a menu from the MenuManager Map of menus.
          * Therefore, a ConcurrentModificationException needs to be avoided using an Iterator.
@@ -141,7 +139,7 @@ public MenuManager<E> closeMenus() {
      * @throws IllegalArgumentException If the {@link Inventory} argument is null
      */
     @NonNull
-    public Optional<E> getMenu(@NonNull Inventory inventory) {
+    public Optional<IMenu> getMenu(@NonNull Inventory inventory) {
         return Optional.ofNullable(this.menus.get(inventory));
     }
 
@@ -154,7 +152,7 @@ public Optional<E> getMenu(@NonNull Inventory inventory) {
      * @throws IllegalArgumentException If the viewer argument is null
      */
     @NonNull
-    public Optional<E> getMenu(@NonNull HumanEntity viewer) {
+    public Optional<IMenu> getMenu(@NonNull HumanEntity viewer) {
         return this.getMenu(viewer.getOpenInventory().getTopInventory());
     }
 
@@ -166,7 +164,7 @@ public Optional<E> getMenu(@NonNull HumanEntity viewer) {
      */
     @NonNull
     @UnmodifiableView
-    public Map<Inventory, E> getMap() {
+    public Map<Inventory, IMenu> getMap() {
         return Collections.unmodifiableMap(this.menus);
     }