Package info files for better JavaDocs (#1839)

* Added package info files for better JavaDocs

src/main/java/world/bentobox/bentobox/api/addons/exceptions/package-info.java

@@ -0,0 +1,10 @@
+/**
+ * This package covers Addon exceptions
+ * <p>
+ * These exceptions can be thrown when the addon is loaded.
+ * </p>
+ *
+ * @since 1.0
+ * @author tastybento
+ */
+package world.bentobox.bentobox.api.addons.exceptions;

src/main/java/world/bentobox/bentobox/api/addons/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * This package covers all addon-specific API
+ * <p>
+ * The Addon class and the associated Pladdon are like Bukkit plugins
+ * but contain extra API specific for BentoBox games.
+ * </p>
+ *
+ * @since 1.0
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.addons;

src/main/java/world/bentobox/bentobox/api/addons/request/package-info.java

@@ -0,0 +1,13 @@
+/**
+ * API to enable plugins to request data from addons.
+ * <p>
+ * Addons can expose data that they want to expose. To access it, call this class with the appropriate addon name,
+ * the label for the data that is requested and if required, a map of key-value pairs that will be given to the addon.
+ *
+ * <b>Note</b> Since BentoBox 1.17.0, Addons can be declared as Pladdons and be loaded by the Bukkit classloader. This
+ * enables Plugins to access Addon methods directly so this API is not required.
+ * </p>
+ *
+ * @author tastybento
+ */
+package world.bentobox.bentobox.api.addons.request;

src/main/java/world/bentobox/bentobox/api/commands/CompositeCommand.java

@@ -33,7 +33,7 @@ import world.bentobox.bentobox.managers.PlayersManager;
 import world.bentobox.bentobox.util.Util;
 
 /**
- * BSB composite command
+ * BentoBox composite command. Provides an abstract implementation of a command.
  * @author tastybento
  * @author Poslovitch
  */

src/main/java/world/bentobox/bentobox/api/commands/package-info.java

@@ -0,0 +1,18 @@
+/**
+ * API for BentoBox commands
+ */
+/**
+ * <p>
+ * The workhorse class is the abstract class CompositeCommand. It provides all the functionality for
+ * a command including automatic help, sub-commands, convenience methods, etc. See examples of how to use
+ * it in the sub-folders admin and island.
+ * </p>
+ * <p>
+ * The package also includes abstract confirmable command and delayed teleport command classes. These can
+ * be extended for commands that need them. There is also a default help command. Commands can implement
+ * their own custom help if required, but most of the time it is not.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.commands;

src/main/java/world/bentobox/bentobox/api/events/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * API for all the events that BentoBox generates
+ */
+/**
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.events;

src/main/java/world/bentobox/bentobox/api/flags/clicklisteners/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * This package contains click listener classes used when clicking on icons in settings
+ *
+ * <p>
+ * CycleClick will cycle through different settings. IslandLock is specific to locking or unlocking an island.
+ * IslandToggleClick is a toggle-based selection. WorldToggleClick toggles world settings.
+ */
+/**
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.flags.clicklisteners;

src/main/java/world/bentobox/bentobox/api/flags/package-info.java

@@ -0,0 +1,16 @@
+/**
+ * This package contains the API for protection and settings flags
+ *
+ * <p>
+ * New flags should usee the Flag.Builder to create a flag. Listeners for flag related events should
+ * extend the abstract FlagListener class.
+ * </p>
+ * <p>
+ * Click listeners are different types of listeners specific to clicking on the settings UI in which the
+ * flags are shown.
+ * </p>
+ *
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.flags;

src/main/java/world/bentobox/bentobox/api/hooks/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * Provides API to enable BentoBox to hook into other plugins.
+ *
+ * <p>
+ * This is used to hook into plugins like Placeholder API
+ * </p>
+ */
+/**
+ * @author Poslovich
+ *
+ */
+package world.bentobox.bentobox.api.hooks;

src/main/java/world/bentobox/bentobox/api/localization/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * API for localization.
+ *
+ * <p>
+ * BentoBoxLocale holds all the information required to specify a locale in BentoBox.
+ * TextVariables contains a static constants that are used as place holders in user messaging.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.localization;

src/main/java/world/bentobox/bentobox/api/metadata/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * Metadata API for storing data in BentoBox database objects
+ * <p>
+ * This API draws on the same concepts as Bukkit's meta data API.
+ * Classes capable of storing meta data will implement the MetaDataAble interface.
+ * MetaDataValue provides the actual object in which data is stored.
+/* </p>
+ * @author tastybento
+ * @since 1.15.4
+ */
+package world.bentobox.bentobox.api.metadata;

src/main/java/world/bentobox/bentobox/api/panels/package-info.java

@@ -0,0 +1,21 @@
+/**
+ * API for GUI panel creation and usage.
+ *
+ * <p>
+ * BentoBox provides an API that enables Addon developers to display a GUI.
+ * There is the basic Panel and the more advanced TabbedPanel. Both use Builders
+ * to make them. For examples, look at the Settings classes.
+ * </p>
+ * <p>
+ * Clicking on a panel item is handled by classes that implement the PanelListener interface.
+ * When a click is made, the listener is called with various parameters available. It is possible
+ * to have an overall listener for the whole panel and also individual listeners just for the
+ * icon that was clicked.
+ * <p>
+ * The tabbed panel contains Tabs that are accessible via icons at the top of the panel.
+ * </p>
+ *
+ * @author tastybento
+ * @since 1.7.0
+ */
+package world.bentobox.bentobox.api.panels;

src/main/java/world/bentobox/bentobox/api/placeholders/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for placeholder replacement.
+ *
+ * @since 1.5.0
+ * @author Poslovitch
+ */
+package world.bentobox.bentobox.api.placeholders;

src/main/java/world/bentobox/bentobox/api/user/package-info.java

@@ -0,0 +1,18 @@
+/**
+ * API for BentoBox Users
+ *
+ * <p>
+ * BentoBox has extended the Bukkit Player class to become a User with the primary reason
+ * to enable localized messaging. Apart from that a User can be an OfflinePlayer, a Player,
+ * or even the Console. Users are used throughout the BentoBox code base, e.g., for commands
+ * instead of Players. It is possible to get a Player from a User if the User is a player.
+ * </p>
+ * <p>
+ * Notifier is a special kind of messaging class that prevents spamming of messages to a
+ * user in chat. It is useful for cases when the same message may be generated many times, e.g., in
+ * a protection scenario.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.api.user;

src/main/java/world/bentobox/bentobox/blueprints/package-info.java

@@ -0,0 +1,10 @@
+/**
+ * This package contains non-API classes that handle Blueprints.
+ *
+ * Blueprints are BentoBox's version of schematics, but contain
+ * additional useful info.
+ *
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.blueprints;

src/main/java/world/bentobox/bentobox/commands/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * The package cotnains non-API commands for BentoBox itself.
+ *
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.commands;

src/main/java/world/bentobox/bentobox/database/json/adapters/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * These are GSON adapters used to serialize and deserialize various data types.
+ * <p>
+ * The {@link world.bentobox.bentobox.database.json.adapters#BukkitObjectTypeAdapter}
+ * is a catch-all adapter that uses the built-in Bukkit serialization capabilities. Before
+ * we knew about this, there were other ones built, like for Location, that have to remain
+ * for backwards compatibility reasons.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.database.json.adapters;

src/main/java/world/bentobox/bentobox/database/objects/adapters/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * These adapters are used by the YAML database, which is now only used
+ * for configuration storage and management. For the GSON adapters used
+ * by the "real" databases, see {@link world.bentobox.bentobox.database.json.adapters}
+ */
+package world.bentobox.bentobox.database.objects.adapters;

src/main/java/world/bentobox/bentobox/database/objects/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * These are the data objects and adapters that BentoBox uses to store its data.
+ *
+ * <p>
+ * Key objects are Island and Players. BentoBox loads all Island objects on startup into RAM. Players are loaded
+ * as and when required.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.database.objects;

src/main/java/world/bentobox/bentobox/database/package-info.java

@@ -0,0 +1,21 @@
+/**
+ * Provides an abstract database for storing Java POJOs
+ * and also YAML config files.
+ *
+ * <p>
+ * The database supports concrete implementations for JSON flat file, MongoDB, MySQL, PostgreSQL, SQLite
+ * and the ability to transition between them.
+ * </p>
+ * <p>
+ * Storage of POJOs is done via GSON, i.e, the object is serialized and then stored. Each ddata object must
+ * implement the DataObject interface, which requires a uniquId field. This is what is used for indexing
+ * and finding.
+ * </p>
+ * <p>
+ * Performance with JSON is generally very good, and the other databases are really there for concurrent usage
+ * by other applications.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.database;

src/main/java/world/bentobox/bentobox/hooks/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * This is where hooks into other plugins go.
+ *
+ * @author Poslovitch
+ *
+ */
+package world.bentobox.bentobox.hooks;

src/main/java/world/bentobox/bentobox/listeners/flags/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Contains listeners specific to settings flags.
+ *
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.listeners.flags;

src/main/java/world/bentobox/bentobox/lists/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * This is where lists of things are put. For example Flags.
+ *
+ * @author tastybento, Poslovitch
+ *
+ */
+package world.bentobox.bentobox.lists;

src/main/java/world/bentobox/bentobox/nms/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * Contains NMS related classes.
+ *
+ * <p>
+ * Due to limitations in Maven and public building on CI's, only the most recent version of Minecraft
+ * is supported.
+ * </p>
+ *
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.nms;

src/main/java/world/bentobox/bentobox/panels/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * Contains non-API panel implementations used by BentoBox
+ *
+ * <p>
+ * These are GUIs such as the settings, blueprints, island creation panels, etc.
+ * They use the Panel API.
+ * </p>
+ * @author tastybento
+ *
+ */
+package world.bentobox.bentobox.panels;

src/main/java/world/bentobox/bentobox/util/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * API that provides useful (and not so useful) utility functions.
+ *
+ * <p>
+ * Look here before you write your own utility function. If it isn't here, but would be useful
+ * the submit a PR so others can avoid duplicating code!
+ * </p>
+ *
+ * @author various
+ *
+ */
+package world.bentobox.bentobox.util;

src/main/java/world/bentobox/bentobox/versions/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * Holds a class that decides whether BentoBox is compatible with the server or not.
+ *
+ * <p>
+ * This has to be updated with each new release of the server.
+ * </p>
+ *
+ * @author Poslovich
+ *
+ */
+package world.bentobox.bentobox.versions;

src/main/java/world/bentobox/bentobox/web/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Fetches data from the web, such as the catalog.
+ *
+ * @author Poslovitch
+ *
+ */
+package world.bentobox.bentobox.web;