added some more jdoc to api; added FluidTankInfo type converter; made robot interface extend rotatable

src/main/java/li/cil/oc/api/CreativeTab.java

@@ -9,7 +9,9 @@ public final class CreativeTab {
     /**
      * The creative tab used by OpenComputers.
      * <p/>
-     * Changed to the actual tab if OC is present.
+     * Changed to the actual tab if OC is present. Preferably you do
+     * <em>not</em> try to access this anyway when OpenComputers isn't
+     * present (don't ship the API in your mod), so don't rely on this!
      */
     public static CreativeTabs Instance = CreativeTabs.tabRedstone;
 

src/main/java/li/cil/oc/api/Driver.java

@@ -32,7 +32,8 @@ public final class Driver {
      * @param driver the driver to register.
      */
     public static void add(final Block driver) {
-        if (instance != null) instance.add(driver);
+        if (instance != null)
+            instance.add(driver);
     }
 
     /**
@@ -47,7 +48,8 @@ public final class Driver {
      * @param driver the driver to register.
      */
     public static void add(final Item driver) {
-        if (instance != null) instance.add(driver);
+        if (instance != null)
+            instance.add(driver);
     }
 
     /**
@@ -62,7 +64,8 @@ public final class Driver {
      * @param converter the converter to register.
      */
     public static void add(final Converter converter) {
-        if (instance != null) instance.add(converter);
+        if (instance != null)
+            instance.add(converter);
     }
 
     // ----------------------------------------------------------------------- //

src/main/java/li/cil/oc/api/Machine.java

@@ -35,7 +35,8 @@ public final class Machine {
      * @param architecture the architecture to register.
      */
     public static void add(Class<? extends Architecture> architecture) {
-        if (instance != null) instance.add(architecture);
+        if (instance != null)
+            instance.add(architecture);
     }
 
     /**
@@ -71,7 +72,8 @@ public final class Machine {
      * until it also created a new machine using that architecture.
      */
     public static Iterable<Class<? extends Architecture>> architectures() {
-        if (instance != null) return instance.architectures();
+        if (instance != null)
+            return instance.architectures();
         return Collections.emptyList();
     }
 
@@ -87,7 +89,8 @@ public final class Machine {
      * @throws IllegalArgumentException if the specified architecture is invalid.
      */
     public static li.cil.oc.api.machine.Machine create(Owner owner, Class<? extends Architecture> architecture) {
-        if (instance != null) return instance.create(owner, architecture);
+        if (instance != null)
+            return instance.create(owner, architecture);
         return null;
     }
 
@@ -101,7 +104,8 @@ public final class Machine {
      * @return the newly created machine.
      */
     public static li.cil.oc.api.machine.Machine create(Owner owner) {
-        if (instance != null) return instance.create(owner, LuaArchitecture);
+        if (instance != null)
+            return instance.create(owner, LuaArchitecture);
         return null;
     }
 

src/main/java/li/cil/oc/api/detail/Builder.java

@@ -8,30 +8,139 @@ import li.cil.oc.api.network.*;
  * @param <T> the type of the node created by this builder.
  */
 public interface Builder<T extends Node> {
+    /**
+     * Finalizes the construction of the node.
+     * <p/>
+     * This performs the actual creation of the node, initializes it to the
+     * settings defined by the current builder and returns it.
+     *
+     * @return the final node.
+     */
     T create();
 
+    /**
+     * Builder for basic nodes. These nodes merely allow network access and
+     * take on no special role.
+     */
     public static interface NodeBuilder extends Builder<Node> {
-        ComponentBuilder withComponent(final String name);
+        /**
+         * Makes the node a component.
+         * <p/>
+         * Nodes that are components can be accessed from computers, methods
+         * declared in them marked using the {@link Callback} annotation can
+         * be invoked from computers that can see the component.
+         *
+         * @param name       the name of the component.
+         * @param visibility the visibility of the component.
+         * @return a builder for a node that is also a component.
+         * @see li.cil.oc.api.network.Component
+         */
+        ComponentBuilder withComponent(String name, Visibility visibility);
 
-        ComponentBuilder withComponent(final String name, final Visibility visibility);
+        /**
+         * Makes the node a component.
+         * <p/>
+         * Like {@link #withComponent(String, Visibility)}, but with a default
+         * visibility set to the <em>reachability</em> of the node.
+         *
+         * @param name the name of the component.
+         * @return a builder for a node that is also a component.
+         * @see li.cil.oc.api.network.Component
+         */
+        ComponentBuilder withComponent(String name);
 
+        /**
+         * Makes the node a connector.
+         * <p/>
+         * A connector node can feed power into the network and extract power
+         * from the network. This is used both for passive energy drain (such
+         * as running screens and computers) and for active power consumption
+         * (such as wireless message sending or robot actions).
+         *
+         * @param bufferSize the size of the local energy buffer.
+         * @return a builder for a node that is also a connector.
+         * @see li.cil.oc.api.network.Connector
+         */
+        ConnectorBuilder withConnector(double bufferSize);
+
+        /**
+         * Makes the node a connector.
+         * <p/>
+         * Like {@link #withConnector(double)}, but with a default buffer size
+         * of zero.
+         *
+         * @return a builder for a node that is also a connector.
+         * @see li.cil.oc.api.network.Connector
+         */
         ConnectorBuilder withConnector();
-
-        ConnectorBuilder withConnector(final double bufferSize);
     }
 
+    /**
+     * Builder for component nodes. These node can be interacted with from
+     * computers in the same network, that can <em>see</em> the component.
+     */
     public static interface ComponentBuilder extends Builder<Component> {
+        /**
+         * Makes the node a connector.
+         * <p/>
+         * A connector node can feed power into the network and extract power
+         * from the network. This is used both for passive energy drain (such
+         * as running screens and computers) and for active power consumption
+         * (such as wireless message sending or robot actions).
+         *
+         * @param bufferSize the size of the local energy buffer.
+         * @return a builder for a node that is also a connector.
+         * @see li.cil.oc.api.network.Connector
+         */
+        ComponentConnectorBuilder withConnector(double bufferSize);
+
+        /**
+         * Makes the node a connector.
+         * <p/>
+         * Like {@link #withConnector(double)}, but with a default buffer size
+         * of zero.
+         *
+         * @return a builder for a node that is also a connector.
+         * @see li.cil.oc.api.network.Connector
+         */
         ComponentConnectorBuilder withConnector();
-
-        ComponentConnectorBuilder withConnector(final double bufferSize);
     }
 
+    /**
+     * Builder for connector nodes. These nodes can interact with the energy
+     * stored in the network, i.e. increase or reduce it.
+     */
     public static interface ConnectorBuilder extends Builder<Connector> {
-        ComponentConnectorBuilder withComponent(final String name);
+        /**
+         * Makes the node a component.
+         * <p/>
+         * Nodes that are components can be accessed from computers, methods
+         * declared in them marked using the {@link Callback} annotation can
+         * be invoked from computers that can see the component.
+         *
+         * @param name       the name of the component.
+         * @param visibility the visibility of the component.
+         * @return a builder for a node that is also a component.
+         * @see li.cil.oc.api.network.Component
+         */
+        ComponentConnectorBuilder withComponent(String name, Visibility visibility);
 
-        ComponentConnectorBuilder withComponent(final String name, final Visibility visibility);
+        /**
+         * Makes the node a component.
+         * <p/>
+         * Like {@link #withComponent(String, Visibility)}, but with a default
+         * visibility set to the <em>reachability</em> of the node.
+         *
+         * @param name the name of the component.
+         * @return a builder for a node that is also a component.
+         * @see li.cil.oc.api.network.Component
+         */
+        ComponentConnectorBuilder withComponent(String name);
     }
 
+    /**
+     * Builder for nodes that are both component <em>and</em> connector node.
+     */
     public static interface ComponentConnectorBuilder extends Builder<ComponentConnector> {
     }
 }

src/main/java/li/cil/oc/api/detail/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * This package contains implementation detail interfaces. You will not have to
+ * interact with these interfaces directly (except for the <tt>Builder</tt>),
+ * and you particularly should not implement these interfaces yourself.
+ */
+package li.cil.oc.api.detail;

src/main/java/li/cil/oc/api/driver/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * This package contains driver related interfaces.
+ * <p/>
+ * Drivers are used to add items and third party blocks to the internal network,
+ * which is mostly used to make components wrapping them available to computers.
+ */
+package li.cil.oc.api.driver;

src/main/java/li/cil/oc/api/fs/package-info.java

@@ -0,0 +1,16 @@
+/**
+ * This package contains interfaces used by the file system implementation.
+ * <p/>
+ * This allows it to add custom file systems that will behave the same as the
+ * existing ones, particularly that can be used the same from a machine as any
+ * other. In the case of Lua, for example, this means it can be mounted like
+ * any other file system, and interacted with without further special handling.
+ * <p/>
+ * <em>You will usually not need to implement these interfaces!</em>
+ * <p/>
+ * Consider using the factory methods in {@link li.cil.oc.api.FileSystem} to
+ * create file systems and wrapper nodes for these file systems (i.e. nodes
+ * that can be added as component nodes to the network, so they can be used
+ * from computers).
+ */
+package li.cil.oc.api.fs;

src/main/java/li/cil/oc/api/machine/Robot.java

@@ -1,5 +1,6 @@
 package li.cil.oc.api.machine;
 
+import li.cil.oc.api.Rotatable;
 import net.minecraft.entity.player.EntityPlayer;
 
 /**
@@ -9,7 +10,7 @@ import net.minecraft.entity.player.EntityPlayer;
  * case, the robot in question is the tile entity passed to item driver when
  * asked to create the component's environment.
  */
-public interface Robot {
+public interface Robot extends Rotatable {
     /**
      * Returns the fake player used to represent the robot as an entity for
      * certain actions that require one.

src/main/java/li/cil/oc/api/machine/package-info.java

@@ -0,0 +1,19 @@
+/**
+ * This package provides low level machine access.
+ * <p/>
+ * Using the {@link li.cil.oc.api.Machine} class, you can create new machine
+ * instances, i.e. essentially computer "cores", that will run code. This allows
+ * you to implement your own computer blocks. Or robots. Or whatever you come up
+ * with.
+ * <p/>
+ * The interfaces in here also allow you to implement an arbitrary new
+ * {@link li.cil.oc.api.machine.Architecture}, which can then be used when
+ * creating a new {@link li.cil.oc.api.machine.Machine} using the factory
+ * methods in {@link li.cil.oc.api.Machine}. An architecture could be a custom
+ * language interpreter, or a full blown hardware emulator for old microchips.
+ * <p/>
+ * There are also a couple of interfaces in here that are not meant to be
+ * implemented, but merely to allow accessing some mod internals in a regulated
+ * fashion, such as {@link li.cil.oc.api.machine.Robot}.
+ */
+package li.cil.oc.api.machine;

src/main/java/li/cil/oc/api/package-info.java

@@ -37,5 +37,5 @@
 @cpw.mods.fml.common.API(
         owner = "OpenComputers|Core",
         provides = "OpenComputersAPI",
-        apiVersion = "1.4.8")
+        apiVersion = "1.4.9")
 package li.cil.oc.api;

src/main/scala/li/cil/oc/common/Proxy.scala

@@ -19,7 +19,7 @@ import li.cil.oc.util.LuaStateFactory
 import net.minecraftforge.common.MinecraftForge
 
 class Proxy {
-  def preInit(e: FMLPreInitializationEvent): Unit = {
+  def preInit(e: FMLPreInitializationEvent) {
     Settings.load(e.getSuggestedConfigurationFile)
 
     Blocks.init()
@@ -44,7 +44,7 @@ class Proxy {
       Settings.resourceDomain + "/lua/rom")
   }
 
-  def init(e: FMLInitializationEvent): Unit = {
+  def init(e: FMLInitializationEvent) {
     api.Driver.add(driver.item.AbstractBusCard)
     api.Driver.add(driver.item.FileSystem)
     api.Driver.add(driver.item.GraphicsCard)
@@ -61,6 +61,7 @@ class Proxy {
     api.Driver.add(driver.item.UpgradeSolarGenerator)
     api.Driver.add(driver.item.WirelessNetworkCard)
 
+    api.Driver.add(driver.converter.FluidTankInfo)
     api.Driver.add(driver.converter.ItemStack)
 
     Recipes.init()
@@ -69,7 +70,7 @@ class Proxy {
     Loot.init()
   }
 
-  def postInit(e: FMLPostInitializationEvent): Unit = {
+  def postInit(e: FMLPostInitializationEvent) {
     // Don't allow driver registration after this point, to avoid issues.
     driver.Registry.locked = true
 

src/main/scala/li/cil/oc/server/driver/converter/FluidTankInfo.scala

@@ -0,0 +1,25 @@
+package li.cil.oc.server.driver.converter
+
+import java.util
+import li.cil.oc.api
+import net.minecraftforge.fluids
+import scala.collection.convert.WrapAsScala._
+
+object FluidTankInfo extends api.driver.Converter {
+  override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) =
+    value match {
+      case tankInfo: fluids.FluidTankInfo =>
+        output += "capacity" -> Int.box(tankInfo.capacity)
+        if (tankInfo.fluid != null) {
+          output += "amount" -> Int.box(tankInfo.fluid.amount)
+          output += "id" -> Int.box(tankInfo.fluid.fluidID)
+          val fluid = tankInfo.fluid.getFluid
+          if (fluid != null) {
+            output += "name" -> fluid.getName
+            output += "label" -> fluid.getLocalizedName
+          }
+        }
+        else output += "amount" -> Int.box(0)
+      case _ =>
+    }
+}

src/main/scala/li/cil/oc/server/driver/converter/ItemStack.scala

@@ -6,7 +6,7 @@ import net.minecraft.item
 import scala.collection.convert.WrapAsScala._
 
 object ItemStack extends api.driver.Converter {
-  override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) = {
+  override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) =
     value match {
       case stack: item.ItemStack =>
         output += "id" -> Int.box(stack.itemID)
@@ -21,5 +21,4 @@ object ItemStack extends api.driver.Converter {
         }
       case _ =>
     }
-  }
 }