make it build (add javadocs and etc.)

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

@@ -31,8 +31,8 @@
 /**
  * Displays a non-text object.
  *
- * @sinceMinecraft 1.21.9
  * @since 4.25.0
+ * @sinceMinecraft 1.21.9
  */
 public interface ObjectComponent extends BuildableComponent<ObjectComponent, ObjectComponent.Builder>, ScopedComponent<ObjectComponent> {
   /**

api/src/main/java/net/kyori/adventure/text/object/PlayerHeadObjectContents.java

@@ -40,30 +40,102 @@
 /**
  * A player head contents.
  *
- * @sinceMinecraft 1.21.9
+ * <p>This object closely mirrors the serialized form of the component contents. This means
+ * the game will use it's standard heuristics to determine whether the profile needs resolving
+ * before display. As of 1.21.9, the profile will be resolved if the name or id is present without
+ * any properties.</p>
+ *
  * @since 4.25.0
+ * @sinceMinecraft 1.21.9
  */
 public interface PlayerHeadObjectContents extends ObjectContents {
+  /**
+   * Gets the name of the player if present.
+   *
+   * @return the name of the player or null
+   * @since 4.25.0
+   */
   @Nullable String name();
 
+  /**
+   * Gets the UUID of the player if present.
+   *
+   * @return the UUID of the player or null
+   * @since 4.25.0
+   */
   @Nullable UUID id();
 
+  /**
+   * Gets the profile properties for the player.
+   *
+   * @return the properties
+   * @since 4.25.0
+   */
   @Unmodifiable
-  @NotNull Map<String, ProfileProperty> properties();
+  @NotNull Map<String, ProfileProperty> profileProperties();
 
+  /**
+   * Whether the player head should render the player's hat layer.
+   *
+   * @return whether to render the hat layer
+   * @since 4.25.0
+   */
   boolean hat();
 
+  /**
+   * Creates a builder from the state of this object.
+   *
+   * @return a new builder
+   * @since 4.25.0
+   */
+  @Contract(value = "-> new", pure = true)
+  @NotNull Builder toBuilder();
+
+  /**
+   * Creates a profile property with the given value and no signature.
+   *
+   * @param value the value
+   * @return a profile property
+   * @since 4.25.0
+   */
+  @Contract(value = "_ -> new", pure = true)
   static ProfileProperty property(final @NotNull String value) {
     return new PlayerHeadObjectContentsImpl.ProfilePropertyImpl(requireNonNull(value, "value"), null);
   }
 
+  /**
+   * Creates a profile property with the given value and signature.
+   *
+   * @param value     the value
+   * @param signature the signature, may be null
+   * @return a profile property
+   * @since 4.25.0
+   */
+  @Contract(value = "_, _ -> new", pure = true)
   static ProfileProperty property(final @NotNull String value, final @Nullable String signature) {
     return new PlayerHeadObjectContentsImpl.ProfilePropertyImpl(requireNonNull(value, "value"), signature);
   }
 
+  /**
+   * A player profile property value with an optional signature.
+   *
+   * @since 4.25.0
+   */
   interface ProfileProperty extends Examinable {
+    /**
+     * Gets the value of the property.
+     *
+     * @return the value
+     * @since 4.25.0
+     */
     @NotNull String value();
 
+    /**
+     * Gets the signature of the property, if present.
+     *
+     * @return the signature or null
+     * @since 4.25.0
+     */
     @Nullable String signature();
 
     @Override
@@ -80,40 +152,125 @@ interface ProfileProperty extends Examinable {
     return Stream.of(
       ExaminableProperty.of("name", this.name()),
       ExaminableProperty.of("id", this.id()),
-      ExaminableProperty.of("properties", this.properties())
+      ExaminableProperty.of("profileProperties", this.profileProperties())
     );
   }
 
+  /**
+   * A builder for a {@link PlayerHeadObjectContents}.
+   *
+   * @since 4.25.0
+   */
   interface Builder {
+    /**
+     * Sets the name of the player.
+     *
+     * @param name the name of the player, may be null
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_ -> this")
     @NotNull Builder name(final @Nullable String name);
 
+    /**
+     * Sets the UUID of the player.
+     *
+     * @param id the UUID of the player, may be null
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_ -> this")
     @NotNull Builder id(final @Nullable UUID id);
 
+    /**
+     * Sets a profile property.
+     *
+     * @param name the name of the property
+     * @param property the property
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_, _ -> this")
-    @NotNull Builder property(final @NotNull String name, final @NotNull ProfileProperty property);
+    @NotNull Builder profileProperty(final @NotNull String name, final @NotNull ProfileProperty property);
 
+    /**
+     * Sets a profile property with the given value and optional signature.
+     *
+     * @param name the name of the property
+     * @param value the value of the property
+     * @param signature the signature of the property, may be null
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_, _, _ -> this")
-    @NotNull Builder property(final @NotNull String name, final @NotNull String value, final @Nullable String signature);
+    @NotNull Builder profileProperty(final @NotNull String name, final @NotNull String value, final @Nullable String signature);
 
+    /**
+     * Sets a profile property with the given value and no signature.
+     *
+     * @param name the name of the property
+     * @param value the value of the property
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_, _ -> this")
-    @NotNull Builder property(final @NotNull String name, final @NotNull String value);
+    @NotNull Builder profileProperty(final @NotNull String name, final @NotNull String value);
 
+    /**
+     * Sets multiple profile properties.
+     *
+     * @param properties the properties
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_ -> this")
-    @NotNull Builder properties(final @NotNull Map<String, ProfileProperty> properties);
+    @NotNull Builder profileProperties(final @NotNull Map<String, ProfileProperty> properties);
 
+    /**
+     * Sets the skin (name, id, and properties) from the given source, overriding any existing values.
+     *
+     * @param skinSource the skin source
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_ -> this")
     @NotNull Builder skin(final @NotNull SkinSource skinSource);
 
+    /**
+     * Sets whether the player head should render the player's hat layer.
+     *
+     * @param hat whether to render the hat layer
+     * @return this builder
+     * @since 4.25.0
+     */
     @Contract(value = "_ -> this")
     @NotNull Builder hat(final boolean hat);
 
+    /**
+     * Builds the player head contents.
+     *
+     * @return a new player head contents
+     * @since 4.25.0
+     */
     @Contract(value = "-> new", pure = true)
     @NotNull PlayerHeadObjectContents build();
   }
 
+  /**
+   * A source of player skin data.
+   *
+   * @see Builder#skin(SkinSource)
+   * @see ObjectContents#playerHead(SkinSource, boolean)
+   * @since 4.25.0
+   */
   interface SkinSource {
+    /**
+     * Applies this skin source to the given player head contents builder.
+     *
+     * <p>The name, id, and properties will be cleared prior to calling by the builder.</p>
+     *
+     * @param builder builder to apply to
+     */
     @PlatformAPI
     @ApiStatus.Internal
     void applySkinToPlayerHeadContents(@NotNull Builder builder);

api/src/main/java/net/kyori/adventure/text/object/PlayerHeadObjectContentsImpl.java

@@ -34,13 +34,13 @@
 
 import static java.util.Objects.requireNonNull;
 
-public final class PlayerHeadObjectContentsImpl implements PlayerHeadObjectContents {
+final class PlayerHeadObjectContentsImpl implements PlayerHeadObjectContents {
   private final @Nullable String name;
   private final @Nullable UUID id;
   private final Map<String, ProfileProperty> properties;
   private final boolean hat;
 
-  public PlayerHeadObjectContentsImpl(
+  PlayerHeadObjectContentsImpl(
     final @Nullable String name,
     final @Nullable UUID id,
     final @NotNull Map<String, ProfileProperty> properties,
@@ -67,7 +67,7 @@ public PlayerHeadObjectContentsImpl(
   }
 
   @Override
-  public @NotNull Map<String, ProfileProperty> properties() {
+  public @NotNull Map<String, ProfileProperty> profileProperties() {
     return this.properties;
   }
 
@@ -76,14 +76,19 @@ public boolean hat() {
     return this.hat;
   }
 
+  @Override
+  public @NotNull Builder toBuilder() {
+    return new BuilderImpl(this);
+  }
+
   @Override
   public boolean equals(final @Nullable Object other) {
     if (this == other) return true;
     if (!(other instanceof PlayerHeadObjectContents)) return false;
     final PlayerHeadObjectContentsImpl that = (PlayerHeadObjectContentsImpl) other;
-    return Objects.equals(name, that.name)
-      && Objects.equals(id, that.id)
-      && Objects.equals(properties, that.properties);
+    return Objects.equals(this.name, that.name)
+      && Objects.equals(this.id, that.id)
+      && Objects.equals(this.properties, that.properties);
   }
 
   @Override
@@ -120,8 +125,8 @@ public boolean equals(final @Nullable Object other) {
       if (this == other) return true;
       if (!(other instanceof ProfilePropertyImpl)) return false;
       final ProfilePropertyImpl that = (ProfilePropertyImpl) other;
-      return Objects.equals(value, that.value)
-        && Objects.equals(signature, that.signature);
+      return Objects.equals(this.value, that.value)
+        && Objects.equals(this.signature, that.signature);
     }
 
     @Override
@@ -141,6 +146,16 @@ static final class BuilderImpl implements PlayerHeadObjectContents.Builder {
     private final Map<String, PlayerHeadObjectContents.ProfileProperty> properties = new HashMap<>();
     private boolean hat;
 
+    BuilderImpl() {
+    }
+
+    BuilderImpl(final @NotNull PlayerHeadObjectContentsImpl playerHeadObjectContents) {
+      this.name = playerHeadObjectContents.name;
+      this.id = playerHeadObjectContents.id;
+      this.properties.putAll(playerHeadObjectContents.properties);
+      this.hat = playerHeadObjectContents.hat;
+    }
+
     @Override
     public PlayerHeadObjectContents.@NotNull Builder name(final @Nullable String name) {
       this.name = name;
@@ -154,25 +169,25 @@ static final class BuilderImpl implements PlayerHeadObjectContents.Builder {
     }
 
     @Override
-    public PlayerHeadObjectContents.@NotNull Builder property(final @NotNull String name, final PlayerHeadObjectContents.@NotNull ProfileProperty property) {
+    public PlayerHeadObjectContents.@NotNull Builder profileProperty(final @NotNull String name, final PlayerHeadObjectContents.@NotNull ProfileProperty property) {
       this.properties.put(requireNonNull(name, "name"), requireNonNull(property, "property"));
       return this;
     }
 
     @Override
-    public PlayerHeadObjectContents.@NotNull Builder property(final @NotNull String name, final @NotNull String value, final @Nullable String signature) {
+    public PlayerHeadObjectContents.@NotNull Builder profileProperty(final @NotNull String name, final @NotNull String value, final @Nullable String signature) {
       this.properties.put(requireNonNull(name, "name"), new ProfilePropertyImpl(requireNonNull(value, "value"), signature));
       return this;
     }
 
     @Override
-    public PlayerHeadObjectContents.@NotNull Builder property(final @NotNull String name, final @NotNull String value) {
+    public PlayerHeadObjectContents.@NotNull Builder profileProperty(final @NotNull String name, final @NotNull String value) {
       this.properties.put(requireNonNull(name, "name"), new ProfilePropertyImpl(requireNonNull(value, "value"), null));
       return this;
     }
 
     @Override
-    public PlayerHeadObjectContents.@NotNull Builder properties(final @NotNull Map<String, PlayerHeadObjectContents.ProfileProperty> properties) {
+    public PlayerHeadObjectContents.@NotNull Builder profileProperties(final @NotNull Map<String, PlayerHeadObjectContents.ProfileProperty> properties) {
       this.properties.putAll(requireNonNull(properties, "properties"));
       return this;
     }

api/src/main/java/net/kyori/adventure/text/object/SpriteObjectContents.java

@@ -33,8 +33,8 @@
  *
  * <p>Represents a sprite in an atlas, such as a block texture.</p>
  *
- * @sinceMinecraft 1.21.9
  * @since 4.25.0
+ * @sinceMinecraft 1.21.9
  */
 public interface SpriteObjectContents extends ObjectContents {
   /**

api/src/main/java/net/kyori/adventure/text/object/SpriteObjectContentsImpl.java

@@ -29,7 +29,7 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public final class SpriteObjectContentsImpl implements SpriteObjectContents {
+final class SpriteObjectContentsImpl implements SpriteObjectContents {
   private final Key atlas;
   private final Key sprite;
 

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

@@ -0,0 +1,27 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2025 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.
+ */
+/**
+ * Types related to {@link net.kyori.adventure.text.ObjectComponent}.
+ */
+package net.kyori.adventure.text.object;