docs: add missing p tags and rework existing tag for consistency (#2449)

add implNote when the comment is an implementation detail
remove ignored newlines

Author: ImMorpheus

src/main/java/org/spongepowered/api/Client.java

@@ -42,11 +42,8 @@ public interface Client extends Engine, LocaleSource {
      * Gets the {@link ClientPlayer player} responsible
      * for controlling this client.
      *
-     * <p>
-     *     A client may not always have a local player if browsing menus prior to joining a
-     *     world or server.
-     * </p>
-     *
+     * @implNote A client may not always have a local player if browsing menus prior to joining a
+     * world or server.
      * @return The local player or {@link Optional#empty()} if it is not found
      */
     Optional<LocalPlayer> player();
@@ -55,10 +52,7 @@ public interface Client extends Engine, LocaleSource {
      * Gets the {@link LocalServer server} that powers a local SinglePlayer game instance
      * of a typical Minecraft client.
      *
-     * <p>
-     *     A client will not have a local server if it is outside of SinglePlayer
-     * </p>
-     *
+     * @implNote A client will not have a local server if it is outside of SinglePlayer
      * @return The local server or {@link Optional#empty()} if it is not found
      */
     Optional<LocalServer> server();
@@ -67,10 +61,7 @@ public interface Client extends Engine, LocaleSource {
      * Gets the {@link ClientWorld world} that a typical Minecraft client will be viewing
      * while in some game instance (local or remote).
      *
-     * <p>
-     *     A client will not have a client world if it is browsing the main menus
-     * </p>
-     *
+     * @implNote A client will not have a client world if it is browsing the main menus
      * @return The client world or {@link Optional#empty()}} if it is not found
      */
     Optional<ClientWorld> world();

src/main/java/org/spongepowered/api/Engine.java

@@ -82,8 +82,7 @@ public interface Engine extends RegistryHolder {
     /**
      * Rediscovers all {@link Resource resources} within all {@link Pack pack's} {@link PackContents contents}.
      *
-     * <p>On the server, the future will always be completed.</p>
-     *
+     * @implNote On the server, the future will always be completed.
      * @return A future that completes when reloading is complete
      */
     CompletableFuture<Void> reloadResources();

src/main/java/org/spongepowered/api/Game.java

@@ -195,10 +195,9 @@ default Client client() {
      * services that plugins may provide. Services provided here are
      * scoped to the lifetime of the Game.
      *
-     * <p>The provider will not be available during plugin construction and will
+     * @implNote The provider will not be available during plugin construction and will
      * throw an {@link IllegalStateException} if there is an attempt to access
-     * this before the provider is ready.</p>
-     *
+     * this before the provider is ready.
      * @return The service manager
      */
     ServiceProvider.GameScoped serviceProvider();

src/main/java/org/spongepowered/api/MinecraftVersion.java

@@ -37,12 +37,9 @@ public interface MinecraftVersion extends Comparable<MinecraftVersion> {
     /**
      * Gets the name of this Minecraft version.
      *
-     * <p>
-     * <strong>Note:</strong> The returned name does not necessarily represent
+     * @implNote The returned name does not necessarily represent
      * the name of a Minecraft version. Depending on the client and
      * implementation, this may also just return a numeric value.
-     * </p>
-     *
      * @return The version name
      */
     String name();
@@ -52,21 +49,16 @@ public interface MinecraftVersion extends Comparable<MinecraftVersion> {
      * all of the features in {@link StatusResponse}. These versions are only
      * supported for the {@link ClientPingServerEvent}, normally they should not be
      * able to join the server.
-     * <p>
-     * For Vanilla, this returns {@code true} for all clients older than 1.7.
-     * </p>
      *
+     * @implNote For Vanilla, this returns {@code true} for all clients older than 1.7.
      * @return {@code True} if this version is a legacy version
      */
     boolean isLegacy();
 
     /**
      * Gets the data version of this Minecraft version.
      *
-     * <p>
- *     <strong>Note:</strong> The data version will not be available in a status response.
-     * </p>
-     *
+     * @implNote The data version will not be available in a status response.
      * @return The data version
      */
     OptionalInt dataVersion();

src/main/java/org/spongepowered/api/Platform.java

@@ -46,10 +46,9 @@ public interface Platform {
     /**
      * Retrieves the current {@link Type} the platform is executing on.
      *
-     * <p>A Minecraft instance will have a client and server thread. If the
+     * @implNote A Minecraft instance will have a client and server thread. If the
      * server is executing, this will return {@linkplain Type#SERVER} but
-     * {@link Platform#type()} would return {@linkplain Type#CLIENT}.</p>
-     *
+     * {@link Platform#type()} would return {@linkplain Type#CLIENT}.
      * @return The execution type
      */
     Type executionType();
@@ -72,25 +71,23 @@ public interface Platform {
 
     /**
      * Returns this platform instance, as a key-value map.
+     * <p>
+     * This mechanism allows for platform-specific information like Forge
+     * version.
      *
-     * <p>The returned map instance is connected directly to this platform
+     * @implNote The returned map instance is connected directly to this platform
      * instance. Existing keys like name and version are not modifiable, but
      * new keys are stored in this instance and are shared between any
-     * references to a map obtained through the retrieved map.</p>
-     *
-     * <p>This mechanism allows for platform-specific information like Forge
-     * version.</p>
-     *
+     * references to a map obtained through the retrieved map.
      * @return This platform as a map
      */
     Map<String, Object> asMap();
 
     /**
      * The type of the platform, or where the game is currently running.
-     *
-     * <p>A side is what part of Minecraft this is being run on. The client, or
+     * <p>
+     * A side is what part of Minecraft this is being run on. The client, or
      * the server. The internal server is also treated like a dedicated server.
-     * </p>
      */
     enum Type {
 

src/main/java/org/spongepowered/api/ResourceKey.java

@@ -37,7 +37,7 @@
 /**
  * An object representation of a location or pointer to resources.
  * The key can be represented as a {@link String} by {@link Object#toString()}.
- *
+ * <p>
  * The key is built with two parts:
  * <ol>
  *     <li>The Namespace</li>
@@ -134,9 +134,8 @@ static ResourceKey of(final PluginContainer plugin, final String value) {
     /**
      * Resolves a resource key from a string.
      *
-     * <p>If no namespace is found in {@code formatted} then
-     * {@link #MINECRAFT_NAMESPACE} will be the namespace.</p>
-     *
+     * @implNote If no namespace is found in {@code formatted} then
+     * {@link #MINECRAFT_NAMESPACE} will be the namespace.
      * @param formatted The formatted string to parse
      * @return A new resource key
      */
@@ -146,10 +145,10 @@ static ResourceKey resolve(final String formatted) {
 
     /**
      * Gets this key as a formatted value.
-     *
-     * <p>It is up to the implementation to determine the formatting. In
+     * <p>
+     * It is up to the implementation to determine the formatting. In
      * vanilla Minecraft, keys are formatted as "namespace:value". For example,
-     * "minecraft:carrot".</p>
+     * "minecraft:carrot".
      *
      * @return The key, formatted
      */
@@ -174,11 +173,11 @@ interface Builder extends org.spongepowered.api.util.Builder<ResourceKey, Builde
 
         /**
          * Sets the key's namespace.
-         *
-         * <p>If using a {@link #MINECRAFT_NAMESPACE} or
+         * <p>
+         * If using a {@link #MINECRAFT_NAMESPACE} or
          * {@link #SPONGE_NAMESPACE}, it is preferable to use
          * {@link ResourceKey#minecraft(String)} or
-         * {@link ResourceKey#sponge(String)} instead.</p>
+         * {@link ResourceKey#sponge(String)} instead.
          *
          * @param namespace The namespace to use
          * @return This builder, for chaining

src/main/java/org/spongepowered/api/Server.java

@@ -87,9 +87,8 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
     /**
      * Gets if multiple {@link ServerWorld worlds} will be loaded by the server.
      *
-     * <p>If false, no calls to loading worlds via the {@link WorldManager world manager} or otherwise will
-     * load a world</p>
-     *
+     * @implNote If false, no calls to loading worlds via the {@link WorldManager world manager} or otherwise will
+     * load a world
      * @return True if enabled, false if not
      */
     boolean isMultiWorldEnabled();
@@ -140,8 +139,7 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
     /**
      * Gets the player idle timeout, in minutes.
      *
-     * <p>A value of {@code 0} means the timeout is disabled</p>
-     *
+     * @implNote A value of {@code 0} means the timeout is disabled
      * @return The player idle timeout
      */
     int playerIdleTimeout();
@@ -169,7 +167,7 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
 
     /**
      * Gets if {@link ServerPlayer players} will have their {@link GameMode game mode} set to the default.
-     *
+     * <p>
      * {@link Server#gameMode()}
      *
      * @return True if enforced, false if not
@@ -244,12 +242,11 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
 
     /**
      * Gets a {@link ServerPlayer} by their name.
+     * <p>
+     * This only works for online players.
      *
-     * <p>This only works for online players.</p>
-     *
-     * <p><b>Note: Do not use names for persistent storage, the
-     * Notch of today may not be the Notch of yesterday.</b></p>
-     *
+     * @implNote Do not use names for persistent storage, the
+     * Notch of today may not be the Notch of yesterday.
      * @param name The name to get the player from
      * @return The {@link ServerPlayer} or empty if not found
      */
@@ -258,14 +255,13 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
     /**
      * Gets the 'server' scoreboard. In Vanilla, this is the scoreboard of
      * dimension 0 (the overworld).
+     * <p>
+     * The server scoreboard is used with the Vanilla /scoreboard command,
+     * automatic score updating through criteria, and other things.
      *
-     * <p>The server scoreboard is used with the Vanilla /scoreboard command,
-     * automatic score updating through criteria, and other things.</p>
-     *
-     * <p>The server scoreboard may not be available if dimension 0
+     * @implNote The server scoreboard may not be available if dimension 0
      * is not yet loaded. In Vanilla, this will only occur when the
-     * server is first starting, as dimension 0 is normally always loaded.</p>
-     *
+     * server is first starting, as dimension 0 is normally always loaded.
      * @return the server scoreboard, if available.
      */
     Optional<? extends Scoreboard> serverScoreboard();
@@ -282,9 +278,8 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
      * Gets the time, in ticks, since this server began running for the current
      * session.
      *
-     * <p>This value is not persisted across server restarts, it is set to zero
-     * each time the server starts.</p>
-     *
+     * @implNote This value is not persisted across server restarts, it is set to zero
+     * each time the server starts.
      * @return The number of ticks since this server started running
      */
     Ticks runningTimeTicks();
@@ -322,8 +317,8 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
      * Shuts down the server, and kicks all players with the default kick
      * message.
      *
-     * <p>For the Sponge implementation on the client, this will trigger the
-     * Integrated Server to shutdown a tick later.</p>
+     * @implNote For the Sponge implementation on the client, this will trigger the
+     * Integrated Server to shutdown a tick later.
      */
     void shutdown();
 
@@ -358,8 +353,8 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
 
     /**
      * Gets the target ticks per second for this server.
-     *
-     * <p>This is dependent on the implementation.</p>
+     * <p>
+     * This is dependent on the implementation.
      *
      * @return The target tick per second rate.
      */
@@ -368,8 +363,7 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
     /**
      * Sets the player idle timeout, in minutes.
      *
-     * <p>A value of {@code 0} disables the player idle timeout.</p>
-     *
+     * @implNote A value of {@code 0} disables the player idle timeout.
      * @param timeout The player idle timeout
      */
     void setPlayerIdleTimeout(int timeout);
@@ -379,29 +373,28 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
      * services that plugins may provide. Services provided here are
      * scoped to the lifetime of this Server.
      *
-     * <p>The provider will not be available during plugin construction and will
+     * @implNote The provider will not be available during plugin construction and will
      * throw an {@link IllegalStateException} if there is an attempt to access
-     * this before the provider is ready.</p>
-     *
+     * this before the provider is ready.
      * @return The service manager
      */
     ServiceProvider.ServerScoped serviceProvider();
 
     /**
      * Gets the {@link CommandManager} for executing and inspecting commands.
-     *
-     * <p>Commands must be registered by listening to the
-     * {@link RegisterCommandEvent} instead.</p>
+     * <p>
+     * Commands must be registered by listening to the
+     * {@link RegisterCommandEvent} instead.
      *
      * @return The {@link CommandManager} instance.
      */
     CommandManager commandManager();
 
     /**
      * Gets the map storage for this server
-     *
-     * <p>This allows for control over the server's maps,
-     * including obtaining and creating them</p>
+     * <p>
+     * This allows for control over the server's maps,
+     * including obtaining and creating them
      *
      * @return MapStorage
      */

src/main/java/org/spongepowered/api/Sponge.java

@@ -128,10 +128,9 @@ public static boolean isServerAvailable() {
     /**
      * Gets the {@link Server} instance from the {@link Game} instance.
      *
-     * <p>Note: During various {@link LifecycleEvent events}, a {@link Server} instance
+     * @implNote During various {@link LifecycleEvent events}, a {@link Server} instance
      * may <strong>NOT</strong> be available. Calling {@link Game#server()} during one
-     * will throw an exception. To double check, call {@link #isServerAvailable()}</p>
-     *
+     * will throw an exception. To double check, call {@link #isServerAvailable()}
      * @see Game#server()
      * @see Game#isServerAvailable()
      * @return The server instance
@@ -154,9 +153,8 @@ public static boolean isClientAvailable() {
     /**
      * Gets the {@link Client} instance from the {@link Game} instance.
      *
-     * <p>Note: Not all implementations support a client, consult your
-     * vendor for further information.</p>
-     *
+     * @implNote Not all implementations support a client, consult your
+     * vendor for further information.
      * @see Game#client()
      * @see Game#isClientAvailable()
      * @return The client instance
@@ -207,9 +205,9 @@ public static SqlManager sqlManager() {
     /**
      * Gets the {@link Game} scoped {@link ServiceProvider} for providing
      * services.
-     *
-     * <p>{@link Engine} scoped services, if they exist, can be found on the
-     * respective engine.</p>
+     * <p>
+     * {@link Engine} scoped services, if they exist, can be found on the
+     * respective engine.
      *
      * @return The service provider.
      */