Expand javadocs

.checkstyle/checkstyle.xml

@@ -36,7 +36,7 @@
     <!-- https://checkstyle.org/config_javadoc.html#AtclauseOrder -->
     <module name="AtclauseOrder">
       <property name="violateExecutionOnNonTightHtml" value="true"/>
-      <property name="tagOrder" value="@author, @deprecated, @exception, @param, @return, @serial, @serialData, @serialField, @throws, @see, @since, @version"/>
+      <property name="tagOrder" value="@author, @deprecated, @exception, @param, @return, @serial, @serialData, @serialField, @throws, @see, @since, @sinceMinecraft, @version"/>
     </module>
 
     <!-- https://checkstyle.org/config_imports.html#AvoidStarImport -->
@@ -252,7 +252,7 @@
     <!-- https://checkstyle.org/config_javadoc.html#WriteTag -->
     <!-- https://gitlab.com/stellardrift/stylecheck/-/blob/dev/src/main/java/ca/stellardrift/stylecheck/FilteringWriteTag.java -->
     <module name="FilteringWriteTag">
-      <property name="tag" value="@since"/>
+      <property name="tag" value="@since\s"/>
       <property name="tagFormat" value="\d\.\d+\.\d+"/>
       <property name="tagSeverity" value="ignore"/>
       <property name="minimumScope" value="public"/>

api/src/main/java/net/kyori/adventure/bossbar/BossBar.java

@@ -31,7 +31,20 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A bossbar.
+ * Represents an in-game bossbar which can be shown to the client.
+ * <p>A bossbar consists of:</p>
+ * <dl>
+ *   <dt>name</dt>
+ *   <dd>the title of the bossbar</dd>
+ *   <dt>progress</dt>
+ *   <dd>a number in the range [0,1] representing how much of the bossbar should be filled</dd>
+ *   <dt>color</dt>
+ *   <dd>the {@link Color} of the bossbar; platforms may downsample this for versions below Java Edition 1.9</dd>
+ *   <dt>overlay</dt>
+ *   <dd>{@link Overlay}s decide if the bossbar is continuous or split into segments</dd>
+ *   <dt>flags(optional)</dt>
+ *   <dd>{@link Flag}s are extra actions that can be triggered whenever the bossbar is displayed</dd>
+ * </dl>
  *
  * @since 4.0.0
  */
@@ -433,30 +446,35 @@ enum Color {
      * Pink.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     PINK("pink"),
     /**
      * Blue.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     BLUE("blue"),
     /**
      * Red.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     RED("red"),
     /**
      * Green.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     GREEN("green"),
     /**
      * Yellow.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     YELLOW("yellow"),
     /**
@@ -469,6 +487,7 @@ enum Color {
      * White.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     WHITE("white");
 
@@ -486,7 +505,7 @@ enum Color {
   }
 
   /**
-   * Flags to control toggleable effects of a boss bar.
+   * Flags to control toggleable effects of a bossbar.
    *
    * @since 4.0.0
    */
@@ -495,18 +514,21 @@ enum Flag {
      * If the screen should be darkened.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     DARKEN_SCREEN("darken_screen"),
     /**
      * If boss music should be played.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     PLAY_BOSS_MUSIC("play_boss_music"),
     /**
      * If world fog should be created.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     CREATE_WORLD_FOG("create_world_fog");
 
@@ -526,7 +548,7 @@ enum Flag {
   }
 
   /**
-   * An overlay on the bar component of a boss bar.
+   * An overlay on the bar component of a bossbar.
    *
    * @since 4.0.0
    */
@@ -541,24 +563,28 @@ enum Overlay {
      * A bar with {@code 6} notches.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     NOTCHED_6("notched_6"),
     /**
      * A bar with {@code 10} notches.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     NOTCHED_10("notched_10"),
     /**
      * A bar with {@code 12} notches.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     NOTCHED_12("notched_12"),
     /**
      * A bar with {@code 20} notches.
      *
      * @since 4.0.0
+     * @sinceMinecraft 1.9
      */
     NOTCHED_20("notched_20");
 

api/src/main/java/net/kyori/adventure/identity/Identity.java

@@ -30,14 +30,18 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * An identity.
+ * An identity used to track the sender of messages for the social interaction features
+ * introduced in <em>Minecraft: Java Edition</em> 1.16.4.
  *
  * @since 4.0.0
+ * @sinceMinecraft 1.16
  */
 public interface Identity extends Examinable {
   /**
    * Gets the {@code null} identity.
    *
+   * <p>This should only be used when no players can be linked to a message.</p>
+   *
    * @return the {@code null} identity
    * @since 4.0.0
    */

api/src/main/java/net/kyori/adventure/inventory/Book.java

@@ -27,14 +27,21 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
+
+import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.examination.Examinable;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A signed book.
+ * Represents the in-game interface of a book.
+ *
+ *
+ * <p>Components exceeding the text limit for a page will be truncated client-side
+ * and not moved automatically to the next page.</p>
  *
+ * @see Audience#openBook(Book)
  * @since 4.0.0
  */
 public interface Book extends Buildable<Book, Book.Builder>, Examinable {

api/src/main/java/net/kyori/adventure/key/Key.java

@@ -29,7 +29,27 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A key.
+ * An identifying object used to fetch and/or store unique objects.
+ *
+ * <p>A key consists of:</p>
+ * <dl>
+ *   <dt>namespace</dt>
+ *   <dd>in most cases this should be your plugin or organization name</dd>
+ *   <dt>value</dt>
+ *   <dd>what this key leads to, e.g "translations" or "entity.firework_rocket.blast"</dd>
+ * </dl>
+ *
+ * <p>Valid characters for namespaces are <a href="https://regexr.com/5ibbm">{@code [a-z0-9_.-]}</a>.</p>
+ *
+ * <p>Valid characters for values are <a href="https://regexr.com/5if3m">{@code [a-z0-9/._-]}</a>.</p>
+ *
+ * <p>Some examples of possible custom keys:</p>
+ * <ul>
+ *   <li> my_plugin:translations</li>
+ *   <li> my_plugin:weapon.amazing-weapon_damage-attribute</li>
+ *   <li> my_organization:music.song_1</li>
+ *   <li> my_organization:item.magic_button</li>
+ * </ul>
  *
  * @since 4.0.0
  */

api/src/main/java/net/kyori/adventure/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2020 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Adventure: a serverside user interface library for Minecraft: Java Edition.
+ *
+ * <p>See the <a href="https://docs.adventure.kyori.net/index.html">documentation</a>
+ * for usage and dependency information for this project and associated libraries.</p>
+ */
+package net.kyori.adventure;

api/src/main/java/net/kyori/adventure/sound/Sound.java

@@ -32,8 +32,23 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A sound.
+ * Represents an in-game sound which can be played to the client.
  *
+ * <p>A sound consists of:</p>
+ * <dl>
+ *   <dt>key/type</dt>
+ *   <dd>the resource location of this sound (e.g minecraft:ambient.cave or my_plugin:custom_sound</dd>
+ *   <dt>source</dt>
+ *   <dd>a {@link Source} telling the game where the sound is coming from</dd>
+ *   <dt>volume</dt>
+ *   <dd>a number in the range [0,∞) representing how loud the sound should be played.
+ *   Increasing volume does not actually play the sound louder, but increases the radius
+ *   of where it can be heard</dd>
+ *   <dt>pitch</dt>
+ *   <dd>a number in the range [0,2] representing which pitch the sound should be played at</dd>
+ * </dl>
+ *
+ * @see SoundStop
  * @since 4.0.0
  */
 public interface Sound extends Examinable {

api/src/main/java/net/kyori/adventure/sound/SoundStop.java

@@ -24,6 +24,7 @@
 package net.kyori.adventure.sound;
 
 import java.util.function.Supplier;
+import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.key.Key;
 import net.kyori.examination.Examinable;
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -32,8 +33,14 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A sound stop.
+ * A sound and/or a sound source, used for stopping in-game sounds that
+ * are being played on a game client matching the given sound and/or sound source.
  *
+ * <p>For clarification: a {@link SoundStop} consisting of the sound "ambient.weather.rain" and the source {@link Sound.Source#AMBIENT}
+ * will only stop sounds matching BOTH parameters and not sounds matching only the sound or only the source.</p>
+ *
+ *
+ * @see Audience#stopSound(SoundStop)
  * @since 4.0.0
  */
 public interface SoundStop extends Examinable {

api/src/main/java/net/kyori/adventure/text/BlockNBTComponent.java

@@ -28,9 +28,19 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A block NBT component.
+ * Given an in-game position, this component reads the NBT of the associated block and displays that information.
  *
+ * <p>This component consists of:</p>
+ * <dl>
+ *   <dt>pos</dt>
+ *   <dd>a position in the world the component is being displayed in.</dd>
+ *   <dt>everything in</dt>
+ *   <dd>{@link NBTComponent}</dd>
+ * </dl>
+ *
+ * @see NBTComponent
  * @since 4.0.0
+ * @sinceMinecraft 1.14
  */
 public interface BlockNBTComponent extends NBTComponent<BlockNBTComponent, BlockNBTComponent.Builder>, ScopedComponent<BlockNBTComponent> {
   /**

api/src/main/java/net/kyori/adventure/text/Component.java

@@ -40,14 +40,41 @@
 import net.kyori.adventure.text.format.Style;
 import net.kyori.adventure.text.format.TextColor;
 import net.kyori.adventure.text.format.TextDecoration;
+import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.IntFunction2;
 import net.kyori.examination.Examinable;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * A component.
+ * A Component is an immutable object that represents how text
+ * is displayed Minecraft clients.
+ *
+ * <p>Components can be thought of as the combination of:</p>
+ *
+ * <ul>
+ *  <li>The message the Component wants to display; and</li>
+ *  <li>The {@link Style} of that message.</li>
+ * </ul>
+ *
+ * <p>The most basic component is the {@link TextComponent},
+ * where the message is a simple String. However, other dynamic
+ * Components are available, which are linked to from here and you
+ * are encouraged to explore to better support your plugin/mod.
+ * Factories and builders for all available component types are
+ * provided via this interface.</p>
+ *
+ * <p>Components can be serialized to and deserialized from other
+ * formats via the use of {@link ComponentSerializer component
+ * serializers}. If used within one of our natively supported platforms,
+ * the availability of such serializers may vary, consult the documentation
+ * or support for the given platform should this be the case.</p>
+ *
+ * <p>Further information about Components, along with functional
+ * examples of how they can be used,
+ * <a href="https://docs.adventure.kyori.net/text.html">can be found on
+ * our documentation.</a></p>
  *
  * @see BlockNBTComponent
  * @see EntityNBTComponent
@@ -57,6 +84,7 @@
  * @see StorageNBTComponent
  * @see TextComponent
  * @see TranslatableComponent
+ * @see LinearComponents
  * @since 4.0.0
  */
 public interface Component extends ComponentBuilderApplicable, ComponentLike, Examinable, HoverEventSource<Component> {

api/src/main/java/net/kyori/adventure/text/ComponentBuilderApplicable.java

@@ -23,11 +23,13 @@
  */
 package net.kyori.adventure.text;
 
+import net.kyori.adventure.text.format.StyleBuilderApplicable;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Something that can be applied to a {@link ComponentBuilder}.
  *
+ * @see StyleBuilderApplicable
  * @since 4.0.0
  */
 @FunctionalInterface