Add more docs for Tags, make TagTemplate builder a specific type on creation.

Author: dualspiral

src/main/java/org/spongepowered/api/tag/Tag.java

@@ -33,35 +33,36 @@
 import java.util.Collection;
 
 /**
- * Represents a Tag for a given type.
+ * A {@link ResourceKey resource keyed} collection of {@link Taggable} values
+ * (of type {@code T}).
  *
- * A {@link ResourceKey resource keyed} collection of {@link Taggable} values (of type {@code T}).
- *
- * <p>While any number of tags may exist and the values each tag contains is arbitary,
- * vanilla Minecraft generally uses pre-defined tags for one of the following reasons:</p>
+ * <p>While any number of tags may exist and the values each tag contains is
+ * arbitrary, vanilla Minecraft generally uses pre-defined tags for one of the
+ * following reasons:</p>
  *
  * <ul>
- *     <li>To define a common material that {@link BlockType blocks} are made of,
- *     for example, {@link BlockTypeTags#ACACIA_LOGS}</li>
- *     <li>To define a common behavior that the {@link Engine engine} should apply to a block,
- *     such as specifying a block as a log that can burn via {@link BlockTypeTags#LOGS_THAT_BURN}</li>
+ *     <li>To define a common material that {@link BlockType blocks} are made
+ *     of, for example, {@link BlockTypeTags#ACACIA_LOGS}</li>
+ *     <li>To define a common behavior that the {@link Engine engine} should
+ *     apply to a block, such as specifying a block as a log that can burn via
+ *     {@link BlockTypeTags#LOGS_THAT_BURN}</li>
  * </ul>
- *
  */
 public interface Tag<T> extends DefaultedRegistryValue, ResourceKeyed {
 
     /**
-     * Get every value in this Tag.
+     * Gets all values that are associated with this tag.
      *
      * @return All tag values
      */
     Collection<T> values();
 
     /**
-     * Whether this tag includes the given value.
+     * Gets whether this tag contains the supplied value.
      *
      * @param value Value to check
      * @return Whether the value is contained in this tag.
      */
     boolean contains(T value);
+
 }

src/main/java/org/spongepowered/api/tag/TagTemplate.java

@@ -29,6 +29,7 @@
 import org.spongepowered.api.Sponge;
 import org.spongepowered.api.datapack.DataPackSerializable;
 import org.spongepowered.api.event.lifecycle.RegisterDataPackValueEvent;
+import org.spongepowered.api.registry.DefaultedRegistryReference;
 import org.spongepowered.api.registry.RegistryKey;
 
 import java.util.Collection;
@@ -40,60 +41,102 @@
 public interface TagTemplate extends DataPackSerializable {
 
     /**
-     * Creates a builder to create a new {@link Tag}
-     * or modify an existing one.
-     * @return Builder to build a new Tag.
+     * Returns a {@link Builder} that creates {@link TagTemplate}s.
+     *
+     * @param reference The {@link TagType} of the builder
+     * @return The builder.
      */
     @SuppressWarnings("unchecked")
-    static Builder<?> builder() {
-        return Sponge.game().builderProvider().provide(Builder.class);
+    static <T extends Taggable<T>> Builder<T> builder(final DefaultedRegistryReference<TagType<T>> reference) {
+        return Sponge.game().factoryProvider().provide(Factory.class).builder(reference.get());
+    }
+
+    /**
+     * Returns a {@link Builder} that creates {@link TagTemplate}s.
+     *
+     * @param tagType The {@link TagType} of the builder
+     * @return The builder.
+     */
+    @SuppressWarnings("unchecked")
+    static <T extends Taggable<T>> Builder<T> builder(final TagType<T> tagType) {
+        return Sponge.game().factoryProvider().provide(Factory.class).builder(tagType);
     }
 
     interface Builder<T extends Taggable<T>> extends org.spongepowered.api.util.ResourceKeyedBuilder<TagTemplate, Builder<T>> {
 
         /**
-         * Sets the tag type and generifies the builder.
+         * Sets whether the values contained by a tag template will replace
+         * existing values if a tag with the same {@link #key()} and
+         * {@link TagType} already exists when datapacks are (re)loaded.
          *
-         * @param tagType Type to build a tag for, e.g {@link TagTypes#BLOCK_TYPE}
-         * @return This builder, for chaining
-         */
-        <NT extends Taggable<NT>> Builder<NT> type(TagType<NT> tagType);
-
-        /**
-         * <p>Whether to replace instead of append if the tag already
-         * exists. This replaces any minecraft tag data and any data packs
-         * that are lower priority than this one (the plugin data pack)</p>
+         * <p>If this is set to {@code true}, any previous entries for this
+         * given key-tag type combination will be discarded and the data
+         * in the built template will <strong>replace</strong> the data. If
+         * this is set to {@code false}, the entries in this template will
+         * be <strong>merged</strong> with any existing data. The default
+         * behavior is to merge data.</p>
          *
-         * <p>By default, if the {@link ResourceKey#value()} is the same as
-         * another data pack / plugin, the two will be combined, and their
-         * tags appended to each other.</p>
+         * <p>As no guarantees are made to the order in which templates are
+         * applied when datapacks are (re)loaded, note that replacement will
+         * only act upon templates that have previously been applied.</p>
          *
          * @param replace Whether to replace instead of merge.
          * @return This builder, for chaining.
          */
         Builder<T> replace(boolean replace);
 
+        /**
+         * Indicates that any existing values of a tag with the same
+         * {@link #key()} and {@link TagType} during datapack (re)loading will
+         * have their values discarded and replaced by this template.
+         *
+         * @see #replace(boolean)
+         * @return This builder, for chaining
+         */
         default Builder<T> replace() {
-            return replace(true);
+            return this.replace(true);
         }
 
         /**
          * Adds the {@link RegistryKey} for a value to the builder.
          *
+         * <p>As the objects that this tag will contain may be available at this
+         * stage, their {@link ResourceKey resource key ID} should be provided
+         * instead. However, this gives rise to the possibility that a value
+         * may not be available when tags are generated. The behavior during tag
+         * generation if the a value for the supplied key is not present can be
+         * controlled with the argument passed to the {@code required}
+         * parameter:</p>
+         *
+         * <ul>
+         *     <li>if {@code true}, the entire tag will not be applied.</li>
+         *     <li>if {@code false}, the tag will be applied without the value.
+         *     </li>
+         * </ul>
+         *
          * @param value Value to add
          * @param required Whether this tag should fail to load if
          *                 the value is not found while loading.
          * @return This builder, for chaining
          */
         Builder<T> addValue(RegistryKey<T> value, boolean required);
 
-        default Builder<T> addValue(RegistryKey<T> value) {
-            return addValue(value, true);
+        /**
+         * Adds the {@link RegistryKey} for a value to the builder, marking it
+         * as required.
+         *
+         * @see #addValue(RegistryKey, boolean)
+         * @param value Value to add
+         * @return This builder, for chaining
+         */
+        default Builder<T> addValue(final RegistryKey<T> value) {
+            return this.addValue(value, true);
         }
 
         /**
          * Adds a collection of {@link RegistryKey}s for values to this builder.
          *
+         * @see #addValue(RegistryKey, boolean)
          * @param values Values to add
          * @param required Whether the values are required. If required,
          *                 the tag will fail to load if they are not found
@@ -102,66 +145,117 @@ default Builder<T> addValue(RegistryKey<T> value) {
          */
         Builder<T> addValues(Collection<RegistryKey<T>> values, boolean required);
 
-        default Builder<T> addValues(Collection<RegistryKey<T>> values) {
-            return addValues(values, true);
+        /**
+         * Adds a collection of {@link RegistryKey}s for values to this builder,
+         * marking all as required.
+         *
+         * @see #addValue(RegistryKey, boolean)
+         * @param values Values to add
+         * @return This builder, for chaining.
+         */
+        default Builder<T> addValues(final Collection<RegistryKey<T>> values) {
+            return this.addValues(values, true);
         }
 
         /**
-         * Adds a {@link RegistryKey} for a Tag to this builder.
-         * This means anything contained in that tag, is always
-         * also contained in this one.
+         * Marks a tag with a given {@link RegistryKey} as a child of the tag
+         * generated by this template.
+         *
+         * <p>A child {@link Tag} is considered a subset of its parent, that is,
+         * the tag generated from this template will include all values from all
+         * its children, as well as those directly provided via the addValue(s)
+         * methods.</p>
+         *
+         * <p>As {@link Tag}s may not be available at this stage, their
+         * {@link #key()} should be provided instead. If the key does not point
+         * to a valid tag (or tag template) when datapacks are reloaded, the
+         * argument supplied to {@code required} determines whether this tag
+         * is ultimately generated, that is, if the supplied child key does
+         * not represent a tag:</p>
+         *
+         * <ul>
+         *     <li>if {@code true}, no tag will be generated.</li>
+         *     <li>if {@code false}, a tag will be generated without the given
+         *     child.</li>
+         * </ul>
          *
          * @param childTag {@link RegistryKey} for tag to be added.
          * @param required Whether loading this tag should fail if the child tag is not found.
          * @return This builder, for chaining
          */
         Builder<T> addChild(RegistryKey<Tag<T>> childTag, boolean required);
 
-        default Builder<T> addChild(RegistryKey<Tag<T>> childTag) {
-            return addChild(childTag, true);
+        /**
+         * Marks a tag with a given {@link RegistryKey} as a required child of
+         * the tag generated by this template.
+         *
+         * @see #addChild(RegistryKey)
+         * @param childTag {@link RegistryKey} for tag to be added.
+         * @return This builder, for chaining
+         */
+        default Builder<T> addChild(final RegistryKey<Tag<T>> childTag) {
+            return this.addChild(childTag, true);
         }
 
         /**
          * Adds a child tag to this builder, using a {@link TagTemplate}.
          *
+         * @see #addChild(RegistryKey, boolean)
          * @param childTag The child to be added.
          * @return This builder, for chaining
          * @throws IllegalArgumentException If this TagTemplate is not the same {@link TagType}
-         *                                  as this builder, so is incompatible.
+         *                                  as this builder.
          */
         Builder<T> addChild(TagTemplate childTag) throws IllegalArgumentException;
 
         /**
-         * Adds a collection of children, that are required.
-         * If these are not found they will cause the tag to fail to load.
+         * Adds multiple children to this template.
+         *
+         * @see #addChild(RegistryKey, boolean)
          * @param children Children to add.
-         * @param required Whether to fail loading the tag
-         *                 if these children are not found.
+         * @param required Whether to fail loading the tag if these children are
+         *                 not found.
          * @return This builder, for chaining
          */
         Builder<T> addChildren(Collection<RegistryKey<Tag<T>>> children, boolean required);
 
-        default Builder<T> addChildren(Collection<RegistryKey<Tag<T>>> children) {
-            return addChildren(children, true);
+        /**
+         * Adds multiple required children to this template.
+         *
+         * @see #addChild(RegistryKey, boolean)
+         * @param children Children to add.
+         * @return This builder, for chaining
+         */
+        default Builder<T> addChildren(final Collection<RegistryKey<Tag<T>>> children) {
+            return this.addChildren(children, true);
         }
 
         /**
-         * Adds a map of children to this builder, of
-         * {@link RegistryKey} to whether they are required.
-         * This tag will fail to load if the child tag is not
-         * present and it is required.
+         * Adds multiple required children to this template, where each
+         * key-value pair in this map represents a child {@link ResourceKey}
+         * and whether the child is required.
          *
-         * @param childrenMap Map of children, RegistryKey-Required
+         * @see #addChild(RegistryKey, boolean)
+         * @param childrenMap Map of children, RegistryKey
          * @return This builder, for chaining.
          */
         Builder<T> addChildren(Map<RegistryKey<Tag<T>>, Boolean> childrenMap);
 
         /**
-         * Creates a {@link TagTemplate} that should be registered during the {@link RegisterDataPackValueEvent}.
+         * Creates a {@link TagTemplate} that should be registered during the
+         * {@link RegisterDataPackValueEvent}.
          *
          * @return The built {@link TagTemplate}.
          */
         @Override
-        @NonNull TagTemplate build();
+        @NonNull
+        TagTemplate build();
     }
+
+    interface Factory {
+
+        <T extends Taggable<T>> Builder<T> builder(TagType<T> tagType);
+
+    }
+
 }

src/main/java/org/spongepowered/api/tag/TagType.java

@@ -28,10 +28,27 @@
 import org.spongepowered.api.registry.RegistryType;
 import org.spongepowered.api.util.annotation.CatalogedBy;
 
+/**
+ * Represents a type that can be associated with a {@link Tag}.
+ *
+ * @param <T> The type of {@link Taggable}.
+ */
 @CatalogedBy(TagTypes.class)
 public interface TagType<T extends Taggable<T>> extends DefaultedRegistryValue {
 
+    /**
+     * The {@link RegistryType} that represents the known collection of objects
+     * of type {@code T}.
+     *
+     * @return The {@link RegistryType}
+     */
     RegistryType<T> taggableRegistry();
 
+    /**
+     * The {@link RegistryType} of tags that can be associated with objects.
+     *
+     * @return The {@link RegistryType}
+     */
     RegistryType<Tag<T>> tagRegistry();
+
 }

src/main/java/org/spongepowered/api/tag/Taggable.java

@@ -34,14 +34,18 @@
 public interface Taggable<T extends Taggable<T>> extends DefaultedRegistryValue {
 
     /**
-     * Gets the {@link TagType} for this Taggable
-     * @return This Taggable's TagType
+     * Gets the {@link TagType} that represents the types of {@link Tag tags}
+     * that can be associated with this object.
+     *
+     * @return The {@link TagType}
      */
     TagType<T> tagType();
 
     /**
-     * Gets all tags that this taggable is in.
-     * @return All tags that this taggable is in.
+     * Gets all {@link Tag tags} that have been associated with this object.
+     *
+     * @return The {@link Collection} of {@link Tag}s.
      */
     Collection<Tag<T>> tags();
+
 }