Add JavaDocs

src/main/java/net/shadowfacts/simplemultipart/client/MultipartBakedModel.java

@@ -10,11 +10,27 @@ import java.util.List;
 import java.util.Random;
 
 /**
+ * An extension of the {@link BakedModel} interface for custom code-based multipart models.
+ *
+ * Note: Currently there is no proper way to register these. They can be registered by mixing in to the {@link net.minecraft.client.render.model.ModelLoader}
+ * constructor and injecting them into the {@code bakedModels} map.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public interface MultipartBakedModel extends BakedModel {
 
-	List<BakedQuad> getMultipartQuads(MultipartView view, Direction side, Random random);
+	/**
+	 * Retrieves the quads for a given side of the multipart.
+	 *
+	 * @param view The view of the multipart in the world.
+	 *             {@code null} if the default {@link MultipartBakedModel#getQuads(BlockState, Direction, Random)} implementation
+	 *             is invoked.
+	 * @param side The side that quads are being requested for.
+	 * @param random The position-specific random.
+	 * @return The quads for the given side. The returned quads will be culled whenever the {@code side} is obscured.
+	 */
+	List<BakedQuad> getMultipartQuads(/*@Nullable*/ MultipartView view, Direction side, Random random);
 
 	@Override
 	default List<BakedQuad> getQuads(BlockState state, Direction side, Random random) {

src/main/java/net/shadowfacts/simplemultipart/client/MultipartModelProvider.java

@@ -107,16 +107,6 @@ public class MultipartModelProvider implements ModelProvider {
 		return model;
 	}
 
-//	private StateFactory<Block, BlockState> getStateFactory(class_816 multipartUnbakedModel) {
-//		try {
-//			Field f = class_816.class.getDeclaredField("field_4329");
-//			f.setAccessible(true);
-//			return (StateFactory<Block, BlockState>)f.get(multipartUnbakedModel);
-//		} catch (ReflectiveOperationException e) {
-//			throw new RuntimeException(e);
-//		}
-//	}
-
 	private ModelVariantMap loadPartVariantMap(MultipartFakeBlock blockAdapter, Identifier partStateDefId) throws IOException {
 		Resource resource = null;
 		Reader reader = null;

src/main/java/net/shadowfacts/simplemultipart/container/MultipartContainer.java

@@ -6,20 +6,58 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
 import java.util.Set;
 
 /**
+ * An interface for an object that contains multiparts.
+ * Usually a {@link net.minecraft.block.entity.BlockEntity}; default implementation is {@link AbstractContainerBlockEntity}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public interface MultipartContainer {
 
+	/**
+	 * Retrieves all the multiparts held by this container.
+	 *
+	 * @see MultipartView
+	 * @return All multiparts held by this container.
+	 */
 	Set<MultipartView> getParts();
 
+	/**
+	 * Determines whether the given multipart state can be inserted into this container.
+	 * Checks that the bounding box of the new part does not intersect with any existing ones.
+	 *
+	 * @param state The new multipart state.
+	 * @return If the part can be inserted.
+	 */
 	boolean canInsert(MultipartState state);
 
+	/**
+	 * Performs the insertion of the given multipart into this container.
+	 *
+	 * @param state The new multipart state.
+	 */
 	void insert(MultipartState state);
 
+	/**
+	 * Removes the given multipart from this container.
+	 *
+	 * @see MultipartView
+	 * @param view The part to remove
+	 */
 	void remove(MultipartView view);
 
+	/**
+	 * Breaks the given multipart. Removes it from this container and drops the part as an item.
+	 *
+	 * @param view The part to break.
+	 * @return If the part has been successfully broken.
+	 */
 	boolean breakPart(MultipartView view);
 
+	/**
+	 * Indicates that something about a multipart in this container has changed and it should be saved to disk.
+	 * Does not trigger a network update.
+	 */
 	void schedulePartSave();
 
 }

src/main/java/net/shadowfacts/simplemultipart/item/ItemMultipart.java

@@ -11,13 +11,19 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
 import net.shadowfacts.simplemultipart.util.MultipartPlacementContext;
 
 /**
+ * An {@link Item} implementation that handles placing multiparts.
+ *
+ * Analogous to {@link net.minecraft.item.block.BlockItem}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public class ItemMultipart extends Item {
 
 	protected Multipart part;
 
 	public ItemMultipart(Multipart part) {
+		// TODO: expose settings object?
 		super(new Settings());
 		this.part = part;
 	}
@@ -27,6 +33,15 @@ public class ItemMultipart extends Item {
 		return tryPlace(context);
 	}
 
+	/**
+	 * Attempts to place this item's multipart in the given context.
+	 *
+	 * If the player clicked an existing multipart container, it will attempt to insert into that one, falling back on
+	 * creating a new container.
+	 *
+	 * @param context The item usage context.
+	 * @return The result of the placement.
+	 */
 	protected ActionResult tryPlace(ItemUsageContext context) {
 		// If a multipart inside an existing container was clicked, try inserting into that
 		MultipartContainer hitContainer = getContainer(context);
@@ -65,6 +80,12 @@ public class ItemMultipart extends Item {
 		return container;
 	}
 
+	/**
+	 * Attempts to insert this item's multipart into the container specified by the given context.
+	 *
+	 * @param context The multipart placement context.
+	 * @return If the placement succeeded.
+	 */
 	protected boolean tryPlace(MultipartPlacementContext context) {
 		MultipartState placementState = part.getPlacementState(context);
 

src/main/java/net/shadowfacts/simplemultipart/multipart/Multipart.java

@@ -7,6 +7,7 @@ import net.minecraft.server.world.ServerWorld;
 import net.minecraft.state.StateFactory;
 import net.minecraft.util.Hand;
 import net.minecraft.util.Identifier;
+import net.minecraft.util.math.Direction;
 import net.minecraft.util.shape.VoxelShape;
 import net.minecraft.world.loot.LootSupplier;
 import net.minecraft.world.loot.LootTables;
@@ -15,9 +16,15 @@ import net.shadowfacts.simplemultipart.SimpleMultipart;
 import net.shadowfacts.simplemultipart.util.MultipartPlacementContext;
 
 import java.util.List;
+import java.util.Random;
 
 /**
+ * The base class for a multipart object.
+ *
+ * Analogous to {@link net.minecraft.block.Block}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public abstract class Multipart {
 
@@ -26,6 +33,7 @@ public abstract class Multipart {
 
 	private Identifier dropTableId;
 
+	// TODO: Settings object?
 	public Multipart() {
 		StateFactory.Builder<Multipart, MultipartState> builder = new StateFactory.Builder<>(this);
 		appendProperties(builder);
@@ -33,26 +41,55 @@ public abstract class Multipart {
 		defaultState = stateFactory.getDefaultState();
 	}
 
+	/**
+	 * Used to add additional properties to the state factory.
+	 * @param builder The state factory builder.
+	 */
 	protected void appendProperties(StateFactory.Builder<Multipart, MultipartState> builder) {}
 
+	/**
+	 * @return The default state for this multipart.
+	 */
 	public MultipartState getDefaultState() {
 		return defaultState;
 	}
 
+	/**
+	 * Sets a new default state for this multipart.
+	 * @param defaultState The new default state.
+	 */
 	public void setDefaultState(MultipartState defaultState) {
 		this.defaultState = defaultState;
 	}
 
+	/**
+	 * @return The state factory for this multipart.
+	 */
 	public StateFactory<Multipart, MultipartState> getStateFactory() {
 		return stateFactory;
 	}
 
+	/**
+	 * Used to determine the state that should be used when this multipart is placed in the world from the given context.
+	 *
+	 * For example: determine which half a slab should be or which side a facade should be on.
+	 *
+	 * @param context The context in which this part is being placed.
+	 * @return The state to place.
+	 */
 	public MultipartState getPlacementState(MultipartPlacementContext context) {
 		return getDefaultState();
 	}
 
 	/**
+	 * Can be used to provide additional information to custom {@link net.shadowfacts.simplemultipart.client.MultipartBakedModel}.
+	 * The returned state will be passed to {@link net.shadowfacts.simplemultipart.client.MultipartBakedModel#getMultipartQuads(MultipartView, Direction, Random)}.
+	 *
 	 * Can be overridden, should only be called via {@link MultipartState#getStateForRendering}
+	 *
+	 * @param state The normal state of this multipart.
+	 * @param view The view of this multipart.
+	 * @return The state that will be used for rendering.
 	 */
 	@Deprecated
 	public MultipartState getStateForRendering(MultipartState state, MultipartView view) {
@@ -60,11 +97,22 @@ public abstract class Multipart {
 	}
 
 	/**
+	 * Retrieves the bounding shape this multipart should have.
+	 *
 	 * Can be overridden, should only be called via {@link MultipartState#getBoundingShape}
+	 *
+	 * @param state The specific state for which to return the bounding shape.
+	 * @param view The current view of the multipart.
+	 *             Will be {@code null} when the default bounding shape is determined prior to the part being inserted
+	 *             into the container.
+	 * @return The bounding shape of this multipart in the given state.
 	 */
 	@Deprecated
-	public abstract VoxelShape getBoundingShape(/*@Nullable*/ MultipartState state, MultipartView view);
+	public abstract VoxelShape getBoundingShape(MultipartState state, /*@Nullable*/ MultipartView view);
 
+	/**
+	 * @return The loot table ID used for to determine the drops by the default {@link Multipart#getDroppedStacks(MultipartState, MultipartView, LootContext.Builder)} implementation.
+	 */
 	public Identifier getDropTableId() {
 		if (dropTableId == null) {
 			Identifier id = SimpleMultipart.MULTIPART.getId(this);
@@ -74,7 +122,14 @@ public abstract class Multipart {
 	}
 
 	/**
+	 * Retrieves a list of stacks that should be dropped in the world when this part is broken via {@link net.shadowfacts.simplemultipart.container.MultipartContainer#breakPart(MultipartView)}.
+	 *
 	 * Can be overridden, should only be called via {@link MultipartState#getDroppedStacks)}
+	 *
+	 * @param state The state of this part.
+	 * @param view The view of this part.
+	 * @param builder The {@link LootContext} builder, used by the default loot table-based implementation.
+	 * @return The list of stacks to drop.
 	 */
 	@Deprecated
 	public List<ItemStack> getDroppedStacks(MultipartState state, MultipartView view, LootContext.Builder builder) {
@@ -90,7 +145,15 @@ public abstract class Multipart {
 	}
 
 	/**
+	 * Called when this part is activated (i.e. right-clicked) in the world.
+	 *
 	 * Can be overridden, should only be called via {@link MultipartState#activate}
+	 *
+	 * @param state The state of this part.
+	 * @param view The view of this part.
+	 * @param player The player that activated this part.
+	 * @param hand The hand with which they performed the action.
+	 * @return If the activation was successful. {@code true} will trigger the hand-swinging animation.
 	 */
 	@Deprecated
 	public boolean activate(MultipartState state, MultipartView view, PlayerEntity player, Hand hand) {

src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartState.java

@@ -12,7 +12,12 @@ import net.minecraft.world.loot.context.LootContext;
 import java.util.List;
 
 /**
+ * A container for a {@link Multipart} and its associated properties/values.
+ *
+ * Analogous to {@link net.minecraft.block.BlockState}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public class MultipartState extends AbstractPropertyContainer<Multipart, MultipartState> {
 
@@ -20,25 +25,40 @@ public class MultipartState extends AbstractPropertyContainer<Multipart, Multipa
 		super(part, properties);
 	}
 
+	/**
+	 * @return The multipart object for this state.
+	 */
 	public Multipart getMultipart() {
 		return owner;
 	}
 
+	/**
+	 * @see Multipart#getStateForRendering(MultipartState, MultipartView)
+	 */
 	public MultipartState getStateForRendering(MultipartView view) {
 		//noinspection deprecation
 		return owner.getStateForRendering(this, view);
 	}
 
+	/**
+	 * @see Multipart#getBoundingShape(MultipartState, MultipartView)
+	 */
 	public VoxelShape getBoundingShape(/*@Nullable*/ MultipartView view) {
 		//noinspection deprecation
 		return owner.getBoundingShape(this, view);
 	}
 
+	/**
+	 * @see Multipart#getDroppedStacks(MultipartState, MultipartView, LootContext.Builder)
+	 */
 	public List<ItemStack> getDroppedStacks(MultipartView view, LootContext.Builder builder) {
 		//noinspection deprecated
 		return owner.getDroppedStacks(this, view, builder);
 	}
 
+	/**
+	 * @see Multipart#activate(MultipartState, MultipartView, PlayerEntity, Hand)
+	 */
 	public boolean activate(MultipartView view, PlayerEntity player, Hand hand) {
 		//noinspection deprecated
 		return owner.activate(this, view, player, hand);

src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartView.java

@@ -6,21 +6,55 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
 import net.shadowfacts.simplemultipart.multipart.entity.MultipartEntity;
 
 /**
+ * A view of a multipart and its (optional) associated entity.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 // TODO: better name for this
 public interface MultipartView {
 
+	/**
+	 * @return The container holding this part.
+	 */
 	MultipartContainer getContainer();
 
+	/**
+	 * @return The current state of this multipart.
+	 */
 	MultipartState getState();
 
+	/**
+	 * Sets the new state of this multipart.
+	 *
+	 * Note: This should only be used to change the state of the current {@link Multipart}.
+	 * Changing to a different multipart should be done by removing/breaking the part in the container and then
+	 * inserting the new one.
+	 *
+	 * Setting the state of a multipart will <b>not</b> cause the associated entity to change.
+	 *
+	 * @param state The new state.
+	 */
 	void setState(MultipartState state);
 
-	MultipartEntity getEntity();
+	/**
+	 * @return The entity associated with this part.
+	 */
+	/*@Nullable*/ MultipartEntity getEntity();
 
+	/**
+	 * Sets the entity associated with this part.
+	 *
+	 * This should not usually be called. The associated multipart entity will be created/set by {@link MultipartContainer#insert(MultipartState)}
+	 *
+	 * @param entity The new entity.
+	 */
 	void setEntity(MultipartEntity entity);
 
+	/**
+	 * Helper method for retrieving the multipart object for the current state.
+	 * @return The current multipart.
+	 */
 	default Multipart getMultipart() {
 		return getState().getMultipart();
 	}

src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntity.java

@@ -4,24 +4,50 @@ import net.minecraft.nbt.CompoundTag;
 import net.shadowfacts.simplemultipart.container.MultipartContainer;
 
 /**
+ * An entity associated with multiparts placed in the world. An instance of the part's entity exists for every in-world
+ * instance of the part.
+ *
+ * Can implement {@link net.minecraft.util.Tickable} to be updated on game ticks.
+ *
+ * Analogous to {@link net.minecraft.block.entity.BlockEntity}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public abstract class MultipartEntity {
 
+	/**
+	 * The container holding this multipart entity.
+	 */
+	// TODO: change this to a view?
 	public MultipartContainer container;
 
 	public MultipartEntity(MultipartContainer container) {
 		this.container = container;
 	}
 
+	/**
+	 * Calling this indicates that something about this entity has changed that necessitates saving it to disk.
+	 */
 	protected void scheduleSave() {
 		container.schedulePartSave();
 	}
 
+	/**
+	 * Converts this entity into an NBT tag that can be saved to disk or transferred over the network.
+	 *
+	 * @param tag The tag to save this entity to.
+	 * @return The modified tag.
+	 */
 	public CompoundTag toTag(CompoundTag tag) {
 		return tag;
 	}
 
+	/**
+	 * Restores this entity from the given NBT tag.
+	 *
+	 * @param tag The tag generated by {@link MultipartEntity#toTag(CompoundTag)}.
+	 */
 	public void fromTag(CompoundTag tag) {
 	}
 

src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntityProvider.java

@@ -4,10 +4,22 @@ import net.shadowfacts.simplemultipart.container.MultipartContainer;
 import net.shadowfacts.simplemultipart.multipart.MultipartState;
 
 /**
+ * An interface to be applied to {@link net.shadowfacts.simplemultipart.multipart.Multipart}s that have entities.
+ *
+ * Analogous to {@link net.minecraft.block.BlockEntityProvider}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public interface MultipartEntityProvider {
 
+	/**
+	 * Creates a new multipart entity for this part.
+	 *
+	 * @param state The state of this part.
+	 * @param container The container this part is in.
+	 * @return The new entity. {@code null} if there should not be an entity in this instance.
+	 */
 	/*@Nullable*/
 	MultipartEntity createMultipartEntity(MultipartState state, MultipartContainer container);
 

src/main/java/net/shadowfacts/simplemultipart/util/MultipartHelper.java

@@ -21,10 +21,22 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
 import java.util.*;
 
 /**
+ * Helper methods relating to multiparts.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public class MultipartHelper {
 
+	/**
+	 * Performs a ray trace to determine the hit multipart.
+	 *
+	 * @param container The container being ray traced in.
+	 * @param world The world.
+	 * @param pos The position of the container.
+	 * @param player The player performing the ray trace.
+	 * @return A hit result for the hit multipart. {@ode null} if not part was hit.
+	 */
 	public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, PlayerEntity player) {
 		// copied from BoatItem::use
 		float var6 = MathHelper.lerp(1.0F, player.prevPitch, player.pitch);
@@ -45,6 +57,16 @@ public class MultipartHelper {
 		return rayTrace(container, world, pos, start, end);
 	}
 
+	/**
+	 * Performs a ray trace to determine the hit multipart.
+	 *
+	 * @param container The container being ray traced in.
+	 * @param world The world.
+	 * @param pos The position of the container.
+	 * @param start The start position for the ray.
+	 * @param end The end position for the ray.
+	 * @return A hit result for the hit multipart. {@code null} if no part was hit.
+	 */
 	public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, Vec3d start, Vec3d end) {
 		return container.getParts().stream()
 				.map(view -> {
@@ -57,6 +79,12 @@ public class MultipartHelper {
 				.orElse(null);
 	}
 
+	/**
+	 * Creates a NBT representation of the given multipart state.
+	 *
+	 * @param state The multipart state.
+	 * @return A compound tag containing the multipart and it's property values.
+	 */
 	public static CompoundTag serializeMultipartState(MultipartState state) {
 		CompoundTag tag = new CompoundTag();
 		tag.putString("Name", SimpleMultipart.MULTIPART.getId(state.getMultipart()).toString());
@@ -81,6 +109,13 @@ public class MultipartHelper {
 		return property.getValueAsString(state.get(property));
 	}
 
+	/**
+	 * Retrieves the multipart state specified by the given tag.
+	 *
+	 * @param tag A tag containing the multipart information.
+	 *            Generated by {@link MultipartHelper#serializeMultipartState(MultipartState)}
+	 * @return The multipart state represented by the tag.
+	 */
 	public static MultipartState deserializeMultipartState(CompoundTag tag) {
 		if (!tag.containsKey("Name", 8)) {
 			return null;

src/main/java/net/shadowfacts/simplemultipart/util/MultipartHitResult.java

@@ -1,16 +1,26 @@
 package net.shadowfacts.simplemultipart.util;
 
+import net.minecraft.entity.player.PlayerEntity;
 import net.minecraft.util.HitResult;
 import net.minecraft.util.math.BlockPos;
 import net.minecraft.util.math.Direction;
 import net.minecraft.util.math.Vec3d;
+import net.minecraft.world.World;
+import net.shadowfacts.simplemultipart.container.MultipartContainer;
 import net.shadowfacts.simplemultipart.multipart.MultipartView;
 
 /**
+ * A raytrace result for a multipart.
+ *
  * @author shadowfacts
+ * @since 0.1.0
+ * @see MultipartHelper#rayTrace(MultipartContainer, World, BlockPos, PlayerEntity)
  */
 public class MultipartHitResult extends HitResult {
 
+	/**
+	 * The view of the hit multipart.
+	 */
 	public MultipartView view;
 
 	public MultipartHitResult(Vec3d pos, Direction side, BlockPos blockPos, MultipartView view) {

src/main/java/net/shadowfacts/simplemultipart/util/MultipartPlacementContext.java

@@ -8,7 +8,12 @@ import net.minecraft.util.math.Direction;
 import net.shadowfacts.simplemultipart.container.MultipartContainer;
 
 /**
+ * Contains information about the context in which a multipart is being placed into the world.
+ *
+ * Analogous to {@link net.minecraft.item.ItemPlacementContext}.
+ *
  * @author shadowfacts
+ * @since 0.1.0
  */
 public class MultipartPlacementContext extends ItemUsageContext {
 
@@ -23,6 +28,9 @@ public class MultipartPlacementContext extends ItemUsageContext {
 		this(container, context.getPlayer(), context.getItemStack(), context.getPos(), context.getFacing(), context.getHitX(), context.getHitY(), context.getHitZ());
 	}
 
+	/**
+	 * @return The container that this multipart will be inserted into.
+	 */
 	public MultipartContainer getContainer() {
 		return container;
 	}