diff --git a/src/main/java/net/onrc/onos/api/packet/IPacketService.java b/src/main/java/net/onrc/onos/api/packet/IPacketService.java
index eaa372d..4321a11 100644
--- a/src/main/java/net/onrc/onos/api/packet/IPacketService.java
+++ b/src/main/java/net/onrc/onos/api/packet/IPacketService.java
@@ -4,18 +4,64 @@
 
 import net.floodlightcontroller.core.module.IFloodlightService;
 import net.onrc.onos.core.packet.Ethernet;
-import net.onrc.onos.core.topology.Port;
+import net.onrc.onos.core.util.SwitchPort;
 
+/**
+ * Provides packet services to ONOS applications. This includes both the
+ * ability to receive packets from the network, and to send packets out
+ * ports in the network. The packet service provides a global context for
+ * packet operations; an application can send/receive packets to/from any
+ * port in the network.
+ * <p/>
+ * NOTE: Global packet-ins are currently not implemented. An application can
+ * subscribe to local packet-ins only at the moment.
+ */
 public interface IPacketService extends IFloodlightService {
-    // packet ins
+    /**
+     * Register to listen for packet-in events.
+     *
+     * @param listener the function to call when a packet-in event is received
+     */
     public void registerPacketListener(IPacketListener listener);
 
-    // packet outs
-    public void sendPacket(Port port, Ethernet eth);
+    // TODO investigate using Port objects again when Ports can be safely
+    // passed around.
+    /**
+     * Send a packet out a specific port in the network.
+     *
+     * @param switchPort the port to send the packet out
+     * @param eth the packet to send
+     */
+    public void sendPacket(SwitchPort switchPort, Ethernet eth);
 
-    public void sendPacket(List<Port> ports, Ethernet eth);
+    /**
+     * Send a packet out multiple ports in the network.
+     *
+     * @param switchPorts a list of ports to send the packet out
+     * @param eth the packet to send
+     */
+    public void sendPacket(List<SwitchPort> switchPorts, Ethernet eth);
 
+    /**
+     * Broadcast the packet out all edge ports in the network. An edge port is
+     * defined as any port that doesn't have a link to another switch.
+     *
+     * @param eth the packet to broadcast
+     */
     public void broadcastPacket(Ethernet eth);
 
-    public void broadcastPacket(Ethernet eth, Port inPort);
+    /**
+     * Broadcast the packet out all edge ports in the network, except for the
+     * specified excluded port. An edge port is defined as any port that
+     * doesn't have a link to another switch.
+     * <p/>
+     * This is useful for packets that are received from a host in the
+     * dataplane, where we want to broadcast the packet to everyone apart from
+     * the host that sent it.
+     *
+     * @param eth the packet to broadcast
+     * @param inSwitchPort the exception port that the packet is not
+     * broadcast out
+     */
+    public void broadcastPacket(Ethernet eth, SwitchPort inSwitchPort);
 }