javadoc for wireless api

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

@@ -60,23 +60,70 @@ public final class Network {
             instance.joinNewNetwork(node);
     }
 
+    // ----------------------------------------------------------------------- //
+
+    /**
+     * Makes a wireless endpoint join the wireless network defined by the mod.
+     * <p/>
+     * OpenComputers tracks endpoints to which to send wireless packets sent
+     * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
+     * method. The packets will <em>only</em> be sent to endpoints registered
+     * with the network.
+     * <p/>
+     * <em>Important</em>: when your endpoint is removed from the world,
+     * <em>you must ensure it is also removed from the network</em>!
+     *
+     * @param endpoint the endpoint to register with the network.
+     */
     public static void joinWirelessNetwork(final WirelessEndpoint endpoint) {
         if (instance != null)
             instance.joinWirelessNetwork(endpoint);
     }
 
+    /**
+     * Updates a wireless endpoint in the wireless network.
+     * <p/>
+     * This is more efficient than removing and then adding the node again, as
+     * it only performs the update if the position significantly changed since
+     * the last time the position was updated (more than 0.5 along any axis).
+     * <p/>
+     * Calling this for an endpoint that was not added before does nothing.
+     *
+     * @param endpoint the endpoint for which to update the position.
+     */
     public static void updateWirelessNetwork(final WirelessEndpoint endpoint) {
         if (instance != null)
             instance.updateWirelessNetwork(endpoint);
     }
 
+    /**
+     * Removes a wireless endpoint from the wireless network.
+     * <p/>
+     * This must be called when an endpoint becomes invalid, otherwise it will
+     * remain in the network!
+     * <p/>
+     * Calling this for an endpoint that was not added before does nothing.
+     *
+     * @param endpoint the endpoint to remove from the wireless network.
+     */
     public static void leaveWirelessNetwork(final WirelessEndpoint endpoint) {
         if (instance != null)
             instance.leaveWirelessNetwork(endpoint);
     }
 
-    // ----------------------------------------------------------------------- //
-
+    /**
+     * Sends a packet via the wireless network.
+     * <p/>
+     * This will look for all other registered wireless endpoints in range of
+     * the sender and submit the packets to them. Whether another end point is
+     * reached depends on the distance and potential obstacles between the
+     * sender and the receiver (harder blocks require a stronger signal to be
+     * penetrated).
+     *
+     * @param source   the endpoint that is sending the message.
+     * @param strength the signal strength with which to send the packet.
+     * @param packet   the packet to send.
+     */
     public static void sendWirelessPacket(final WirelessEndpoint source, final double strength, final Packet packet) {
         if (instance != null)
             instance.sendWirelessPacket(source, strength, packet);
@@ -127,12 +174,33 @@ public final class Network {
         return null;
     }
 
+    /**
+     * Creates a new network packet as it would be sent or received by a
+     * network card.
+     * <p/>
+     * These packets can be forwarded by switches and access points. For wired
+     * transmission they must be sent over a node's send method, with the
+     * message name being <tt>network.message</tt>.
+     *
+     * @param source      the address of the sending node.
+     * @param destination the address of the destination, or <tt>null</tt>
+     *                    for a broadcast.
+     * @param port        the port to send the packet to.
+     * @param data        the payload of the packet.
+     * @return the new packet.
+     */
     public static Packet newPacket(final String source, final String destination, final int port, final Object[] data) {
         if (instance != null)
             return instance.newPacket(source, destination, port, data);
         return null;
     }
 
+    /**
+     * Re-creates a network packet from a previously stored state.
+     *
+     * @param nbt the tag to load the packet from.
+     * @return the loaded packet.
+     */
     public static Packet newPacket(final NBTTagCompound nbt) {
         if (instance != null)
             return instance.newPacket(nbt);

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

@@ -34,14 +34,61 @@ public interface NetworkAPI {
      */
     void joinNewNetwork(Node node);
 
-    void joinWirelessNetwork(WirelessEndpoint endpoint);
-
-    void updateWirelessNetwork(WirelessEndpoint endpoint);
-
-    void leaveWirelessNetwork(WirelessEndpoint endpoint);
-
     // ----------------------------------------------------------------------- //
 
+    /**
+     * Makes a wireless endpoint join the wireless network defined by the mod.
+     * <p/>
+     * OpenComputers tracks endpoints to which to send wireless packets sent
+     * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
+     * method. The packets will <em>only</em> be sent to endpoints registered
+     * with the network.
+     * <p/>
+     * <em>Important</em>: when your endpoint is removed from the world,
+     * <em>you must ensure it is also removed from the network</em>!
+     *
+     * @param endpoint the endpoint to register with the network.
+     */
+    void joinWirelessNetwork(WirelessEndpoint endpoint);
+
+    /**
+     * Updates a wireless endpoint in the wireless network.
+     * <p/>
+     * This is more efficient than removing and then adding the node again, as
+     * it only performs the update if the position significantly changed since
+     * the last time the position was updated (more than 0.5 along any axis).
+     * <p/>
+     * Calling this for an endpoint that was not added before does nothing.
+     *
+     * @param endpoint the endpoint for which to update the position.
+     */
+    void updateWirelessNetwork(WirelessEndpoint endpoint);
+
+    /**
+     * Removes a wireless endpoint from the wireless network.
+     * <p/>
+     * This must be called when an endpoint becomes invalid, otherwise it will
+     * remain in the network!
+     * <p/>
+     * Calling this for an endpoint that was not added before does nothing.
+     *
+     * @param endpoint the endpoint to remove from the wireless network.
+     */
+    void leaveWirelessNetwork(WirelessEndpoint endpoint);
+
+    /**
+     * Sends a packet via the wireless network.
+     * <p/>
+     * This will look for all other registered wireless endpoints in range of
+     * the sender and submit the packets to them. Whether another end point is
+     * reached depends on the distance and potential obstacles between the
+     * sender and the receiver (harder blocks require a stronger signal to be
+     * penetrated).
+     *
+     * @param source   the endpoint that is sending the message.
+     * @param strength the signal strength with which to send the packet.
+     * @param packet   the packet to send.
+     */
     void sendWirelessPacket(WirelessEndpoint source, double strength, Packet packet);
 
     // ----------------------------------------------------------------------- //
@@ -85,7 +132,28 @@ public interface NetworkAPI {
      */
     Builder.NodeBuilder newNode(Environment host, Visibility reachability);
 
+    /**
+     * Creates a new network packet as it would be sent or received by a
+     * network card.
+     * <p/>
+     * These packets can be forwarded by switches and access points. For wired
+     * transmission they must be sent over a node's send method, with the
+     * message name being <tt>network.message</tt>.
+     *
+     * @param source      the address of the sending node.
+     * @param destination the address of the destination, or <tt>null</tt>
+     *                    for a broadcast.
+     * @param port        the port to send the packet to.
+     * @param data        the payload of the packet.
+     * @return the new packet.
+     */
     Packet newPacket(String source, String destination, int port, Object[] data);
 
+    /**
+     * Re-creates a network packet from a previously stored state.
+     *
+     * @param nbt the tag to load the packet from.
+     * @return the loaded packet.
+     */
     Packet newPacket(NBTTagCompound nbt);
 }

src/main/java/li/cil/oc/api/network/WirelessEndpoint.java

@@ -6,6 +6,12 @@ import net.minecraft.world.World;
  * Interface for wireless endpoints that can be registered with the internal
  * wireless network registry.
  * <p/>
+ * These can be added to the wireless network via the <tt>Network</tt> API, to
+ * allow them to receive packets like wireless network cards and access points
+ * do (and handle or forward them as they see fit).
+ * <p/>
+ * If the position of the endpoint can change, it must be updated manually via
+ * {@link li.cil.oc.api.Network#updateWirelessNetwork(WirelessEndpoint)}.
  */
 public interface WirelessEndpoint {
     /**

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.7")
+        apiVersion = "1.4.8")
 package li.cil.oc.api;