Improvements to BlockStates

* Update Javadoc of block state classes to better match implementation behaviour.
* Add Container interface which provides access to the snapshot inventory.

By: Lukas Hennig <lukas@wirsindwir.de>

paper-api/src/main/java/org/bukkit/block/Jukebox.java

@@ -3,34 +3,39 @@ package org.bukkit.block;
 import org.bukkit.Material;
 
 /**
- * Represents a Jukebox
+ * Represents a captured state of a jukebox.
  */
 public interface Jukebox extends BlockState {
+
     /**
-     * Get the record currently playing
+     * Gets the record being played.
      *
      * @return The record Material, or AIR if none is playing
      */
     public Material getPlaying();
 
     /**
-     * Set the record currently playing
+     * Sets the record being played.
      *
      * @param record The record Material, or null/AIR to stop playing
      */
     public void setPlaying(Material record);
 
     /**
-     * Check if the jukebox is currently playing a record
+     * Checks if the jukebox is playing a record.
      *
      * @return True if there is a record playing
      */
     public boolean isPlaying();
 
     /**
-     * Stop the jukebox playing and eject the current record
+     * Stops the jukebox playing and ejects the current record.
+     * <p>
+     * If the block represented by this state is no longer a jukebox, this will
+     * do nothing and return false.
      *
      * @return True if a record was ejected; false if there was none playing
+     * @throws IllegalStateException if this block state is not placed
      */
     public boolean eject();
 }