[API-8] Reroute BlockSnapshot#empty into a factory, and add misc miss…

…ing javadocs (SpongePowered#2150)

* Reroute BlockSnapshot#empty into a Factory

* Add missing javadocs

* Adjust for feedback

* Fix grammar error

src/main/java/org/spongepowered/api/block/BlockSnapshot.java

@@ -51,11 +51,11 @@ public interface BlockSnapshot extends LocatableSnapshot<BlockSnapshot> {
     /**
      * Represents a {@link BlockSnapshot} with the default state of
      * {@link BlockTypes#AIR} and a {@link ServerLocation} that cannot be determined.
+     *
+     * @return An empty block snapshot
      */
-    Supplier<BlockSnapshot> NONE = BlockSnapshot::empty;
-
     static BlockSnapshot empty() {
-        return Sponge.game().builderProvider().provide(Builder.class).empty();
+        return Sponge.game().factoryProvider().provide(Factory.class).empty();
     }
 
     /**
@@ -140,13 +140,16 @@ static Builder builder() {
      * Creates a new {@link BlockEntityArchetype} for use with {@link Schematic}s
      * and placing the archetype in multiple locations.
      *
-     * <p>If this blocksnapshot does not contain a block entity then this will
+     * <p>If this block snapshot does not contain a block entity then this will
      * return {@link Optional#empty()}.</p>
      *
      * @return The created archetype for re-creating this block entity
      */
     Optional<BlockEntityArchetype> createArchetype();
 
+    /**
+     * Represents a builder to create {@link BlockSnapshot}s.
+     */
     interface Builder extends SerializableDataHolderBuilder.Immutable<BlockSnapshot, Builder> {
 
         /**
@@ -205,7 +208,20 @@ interface Builder extends SerializableDataHolderBuilder.Immutable<BlockSnapshot,
          * @return This builder, for chaining
          */
         Builder notifier(UUID uuid);
+    }
 
+    /**
+     * Represents a factory to create {@link BlockSnapshot}s.
+     */
+    interface Factory {
+
+        /**
+         * Represents a {@link BlockSnapshot} with the default state of
+         * {@link BlockTypes#AIR}, and a default {@link ServerLocation}
+         * that is decided by the implementation.
+         *
+         * @return An empty block snapshot
+         */
         BlockSnapshot empty();
     }
 }

src/main/java/org/spongepowered/api/block/entity/Bed.java

@@ -28,6 +28,9 @@
 import org.spongepowered.api.data.type.DyeColor;
 import org.spongepowered.api.data.value.Value;
 
+/**
+ * Represents a Bed.
+ */
 public interface Bed extends BlockEntity {
 
     /**

src/main/java/org/spongepowered/api/block/entity/Bell.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity;
 
+/**
+ * Represents a Bell.
+ */
 public interface Bell extends BlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/Conduit.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity;
 
+/**
+ * Represents a Conduit.
+ */
 public interface Conduit extends BlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/Jigsaw.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity;
 
+/**
+ * Represents a Jigsaw.
+ */
 public interface Jigsaw extends BlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/carrier/Barrel.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity.carrier;
 
+/**
+ * Represents a Barrel.
+ */
 public interface Barrel extends NameableCarrierBlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/carrier/Campfire.java

@@ -24,5 +24,8 @@
  */
 package org.spongepowered.api.block.entity.carrier;
 
+/**
+ * Represents a Campfire.
+ */
 public interface Campfire extends CarrierBlockEntity {
 }

src/main/java/org/spongepowered/api/block/entity/carrier/chest/TrappedChest.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity.carrier.chest;
 
+/**
+ * Represents a TrappedChest.
+ */
 public interface TrappedChest extends Chest {
 
 }

src/main/java/org/spongepowered/api/block/entity/carrier/furnace/BlastFurnace.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity.carrier.furnace;
 
+/**
+ * Represents a BlastFurnace.
+ */
 public interface BlastFurnace extends FurnaceBlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/carrier/furnace/Furnace.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity.carrier.furnace;
 
+/**
+ * Represents a Furnace.
+ */
 public interface Furnace extends FurnaceBlockEntity {
 
 }

src/main/java/org/spongepowered/api/block/entity/carrier/furnace/Smoker.java

@@ -24,6 +24,9 @@
  */
 package org.spongepowered.api.block.entity.carrier.furnace;
 
+/**
+ * Represents a Smoker.
+ */
 public interface Smoker extends FurnaceBlockEntity {
 
 }