Added some javadocs (#3217)

Javadocs work by Adrijaned

Author: Adrijaned

engine/src/main/java/org/terasology/utilities/subscribables/AbstractGeneralSubscribable.java

@@ -18,24 +18,15 @@
 import java.beans.PropertyChangeListener;
 import java.beans.PropertyChangeSupport;
 
-/**
- * {@inheritDoc}
- */
 public class AbstractGeneralSubscribable implements GeneralSubscribable {
 
     protected transient PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport(this);
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void subscribe(PropertyChangeListener changeListener) {
         this.propertyChangeSupport.addPropertyChangeListener(changeListener);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void unsubscribe(PropertyChangeListener changeListener) {
         this.propertyChangeSupport.removePropertyChangeListener(changeListener);

engine/src/main/java/org/terasology/utilities/subscribables/AbstractSpecificSubscribable.java

@@ -18,24 +18,15 @@
 import java.beans.PropertyChangeListener;
 import java.beans.PropertyChangeSupport;
 
-/**
- * {@inheritDoc}
- */
 public class AbstractSpecificSubscribable implements SpecificSubscribable {
 
     protected transient PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport(this);
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void subscribe(String propertyName, PropertyChangeListener changeListener) {
         this.propertyChangeSupport.addPropertyChangeListener(propertyName, changeListener);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void unsubscribe(String propertyName, PropertyChangeListener changeListener) {
         this.propertyChangeSupport.removePropertyChangeListener(propertyName, changeListener);

engine/src/main/java/org/terasology/utilities/subscribables/AbstractSubscribable.java

@@ -18,40 +18,25 @@
 import java.beans.PropertyChangeListener;
 import java.beans.PropertyChangeSupport;
 
-/**
- * {@inheritDoc}
- */
 public abstract class AbstractSubscribable implements Subscribable {
 
     protected transient PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport(this);
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void subscribe(PropertyChangeListener changeListener) {
         this.propertyChangeSupport.addPropertyChangeListener(changeListener);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void unsubscribe(PropertyChangeListener changeListener) {
         this.propertyChangeSupport.removePropertyChangeListener(changeListener);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void subscribe(String propertyName, PropertyChangeListener changeListener) {
         this.propertyChangeSupport.addPropertyChangeListener(propertyName, changeListener);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public void unsubscribe(String propertyName, PropertyChangeListener changeListener) {
         this.propertyChangeSupport.removePropertyChangeListener(propertyName, changeListener);

engine/src/main/java/org/terasology/world/block/BlockUri.java

@@ -27,7 +27,7 @@
 /**
  * Identifier for both blocks and block families. It is a combination of the ResourceUrn of a block family definition, the id of a block, and optionally the
  * ResourceUrn of a shape.
- * The final pattern is
+ * The final pattern is (see {@link BlockUri} for details):
  * [package]:[blockFamily]:[shapePackage]:[shapeName].[blockIdentifier]
  * the third and forth parts are only used for blocks that don't use the engine:cube shape, and which
  * are generated from a multi-shape block.

engine/src/main/java/org/terasology/world/chunks/Chunk.java

@@ -19,6 +19,12 @@
 import org.terasology.module.sandbox.API;
 
 /**
+ * Chunks are a box-shaped logical grouping of Terasology's blocks, for performance reasons. 
+ *
+ * For example the renderer renders a single mesh for all opaque blocks in a chunk rather
+ * than rendering each block as a separate mesh.
+ *
+ * For details on dimensions and other chunks characteristics see {@link ChunkConstants}.
  */
 @API
 public interface Chunk extends ManagedChunk, RenderableChunk {

engine/src/main/java/org/terasology/world/chunks/CoreChunk.java

@@ -37,56 +37,211 @@
  */
 @API
 public interface CoreChunk {
+    /**
+     * @return Position of the chunk in world, where units of distance from origin are blocks
+     */
     Vector3i getPosition();
 
+    /**
+     * Returns block at given position relative to the chunk.
+     *
+     * @param pos Position of the block relative to corner of the chunk
+     * @return Block at given position
+     */
     Block getBlock(BaseVector3i pos);
 
+    /**
+     * Returns block at given position relative to the chunk.
+     *
+     * @param x X offset from the corner of the chunk
+     * @param y Y offset from the corner of the chunk
+     * @param z Z offset from the corner of the chunk
+     * @return Block at given position
+     */
     Block getBlock(int x, int y, int z);
 
+    /**
+     * Sets type of block at given position relative to the chunk.
+     *
+     * @param x     X offset from the corner of the chunk
+     * @param y     Y offset from the corner of the chunk
+     * @param z     Z offset from the corner of the chunk
+     * @param block Block to set block at given position to
+     * @return Old Block at given position
+     */
     Block setBlock(int x, int y, int z, Block block);
 
+    /**
+     * Sets type of block at given position relative to the chunk.
+     *
+     * @param pos   Position of the block relative to corner of the chunk
+     * @param block Block to set block at given position to
+     * @return Old Block at given position
+     */
     Block setBlock(BaseVector3i pos, Block block);
 
+    /**
+     * Sets biome at given position relative to the chunk.
+     *
+     * @param x     X offset from the corner of the chunk
+     * @param y     Y offset from the corner of the chunk
+     * @param z     Z offset from the corner of the chunk
+     * @param biome Biome to set block at given position to
+     * @return Old Biome at given position
+     */
     Biome setBiome(int x, int y, int z, Biome biome);
 
+    /**
+     * Sets biome at given position relative to the chunk.
+     *
+     * @param pos   Position of the block relative to corner of the chunk
+     * @param biome Biome to set block at given position to
+     * @return Old Biome at given position
+     */
     Biome setBiome(BaseVector3i pos, Biome biome);
 
+    /**
+     * Returns Biome at given position relative to the chunk.
+     *
+     * @param x X offset from the corner of the chunk
+     * @param y Y offset from the corner of the chunk
+     * @param z Z offset from the corner of the chunk
+     * @return Biome at given position
+     */
     Biome getBiome(int x, int y, int z);
 
+    /**
+     * Returns Biome at given position relative to the chunk.
+     *
+     * @param pos Position of the block relative to corner of the chunk
+     * @return Biome at given position
+     */
     Biome getBiome(BaseVector3i pos);
 
+    /**
+     * Sets liquid state at given position relative to the chunk.
+     *
+     * @param pos   Position of the block relative to corner of the chunk
+     * @param state Liquid state to set the block to
+     */
     void setLiquid(BaseVector3i pos, LiquidData state);
 
+    /**
+     * Sets liquid state at given position relative to the chunk.
+     *
+     * @param x        X offset from the corner of the chunk
+     * @param y        Y offset from the corner of the chunk
+     * @param z        Z offset from the corner of the chunk
+     * @param newState Liquid state to set the block to
+     */
     void setLiquid(int x, int y, int z, LiquidData newState);
 
+    /**
+     * Returns liquid state at given position relative to the chunk.
+     *
+     * @param pos Position of the block relative to corner of the chunk
+     * @return Liquid state currently assigned to the block
+     */
     LiquidData getLiquid(BaseVector3i pos);
 
+    /**
+     * Returns liquid state at given position relative to the chunk.
+     *
+     * @param x X offset from the corner of the chunk
+     * @param y Y offset from the corner of the chunk
+     * @param z Z offset from the corner of the chunk
+     * @return Liquid state currently assigned to the block
+     */
     LiquidData getLiquid(int x, int y, int z);
 
+    /**
+     * Returns offset of this chunk to the world center (0:0:0), with one unit being one chunk.
+     *
+     * @return Offset of this chunk from world center in chunks
+     */
     Vector3i getChunkWorldOffset();
 
+    /**
+     * Returns X offset of this chunk to the world center (0:0:0), with one unit being one chunk.
+     *
+     * @return X offset of this chunk from world center in chunks
+     */
     int getChunkWorldOffsetX();
 
+    /**
+     * Returns Y offset of this chunk to the world center (0:0:0), with one unit being one chunk.
+     *
+     * @return Y offset of this chunk from world center in chunks
+     */
     int getChunkWorldOffsetY();
 
+    /**
+     * Returns Z offset of this chunk to the world center (0:0:0), with one unit being one chunk.
+     *
+     * @return Z offset of this chunk from world center in chunks
+     */
     int getChunkWorldOffsetZ();
 
+    /**
+     * Returns position in this chunk transformed to world coordinates.
+     *
+     * @param blockPos Position in this chunk you want to transform
+     * @return Transformed position
+     */
     Vector3i chunkToWorldPosition(BaseVector3i blockPos);
 
+    /**
+     * Returns position in this chunk transformed to world coordinates.
+     *
+     * @param x X position in this chunk you want to transform
+     * @param y Y position in this chunk you want to transform
+     * @param z Z position in this chunk you want to transform
+     * @return Transformed position
+     */
     Vector3i chunkToWorldPosition(int x, int y, int z);
 
+    /**
+     * Returns X position in this chunk transformed to world coordinate.
+     *
+     * @param x X  position in this chunk you want to transform
+     * @return Transformed position
+     */
     int chunkToWorldPositionX(int x);
 
+    /**
+     * Returns Y position in this chunk transformed to world coordinate.
+     *
+     * @param y Y  position in this chunk you want to transform
+     * @return Transformed position
+     */
     int chunkToWorldPositionY(int y);
 
+    /**
+     * Returns Z position in this chunk transformed to world coordinate.
+     *
+     * @param z Z  position in this chunk you want to transform
+     * @return Transformed position
+     */
     int chunkToWorldPositionZ(int z);
 
+    /**
+     * @return Size of the chunk along the X axis.
+     */
     int getChunkSizeX();
 
+    /**
+     * @return Size of the chunk along the Y axis.
+     */
     int getChunkSizeY();
 
+    /**
+     * @return Size of the chunk along the Z axis.
+     */
     int getChunkSizeZ();
 
+    /**
+     * @return Chunk's Region
+     */
     Region3i getRegion();
 
     int getEstimatedMemoryConsumptionInBytes();