add INTERNAL API markers and explicit return types

akka-actor/src/main/scala/akka/io/SelectionHandler.scala

@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ * Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
  */
 
 package akka.io

akka-actor/src/main/scala/akka/io/Tcp.scala

@@ -106,8 +106,11 @@ object Tcp extends ExtensionKey[TcpExt] {
   case class Received(data: ByteString) extends Event
   case class Connected(remoteAddress: InetSocketAddress, localAddress: InetSocketAddress) extends Event
   case class CommandFailed(cmd: Command) extends Event
-  case object Bound extends Event
+
-  case object Unbound extends Event
+  sealed trait Bound extends Event
+  case object Bound extends Bound
+  sealed trait Unbound extends Event
+  case object Unbound extends Unbound
 
   sealed trait ConnectionClosed extends Event {
     def isAborted: Boolean = false
@@ -190,34 +193,34 @@ object TcpMessage {
 
   def connect(remoteAddress: InetSocketAddress,
               localAddress: InetSocketAddress,
-              options: JIterable[SocketOption]) = Connect(remoteAddress, Some(localAddress), options)
+              options: JIterable[SocketOption]): Command = Connect(remoteAddress, Some(localAddress), options)
   def connect(remoteAddress: InetSocketAddress,
-              options: JIterable[SocketOption]) = Connect(remoteAddress, None, options)
+              options: JIterable[SocketOption]): Command = Connect(remoteAddress, None, options)
-  def connect(remoteAddress: InetSocketAddress) = Connect(remoteAddress, None, Nil)
+  def connect(remoteAddress: InetSocketAddress): Command = Connect(remoteAddress, None, Nil)
 
   def bind(handler: ActorRef,
            endpoint: InetSocketAddress,
            backlog: Int,
-           options: JIterable[SocketOption]) = Bind(handler, endpoint, backlog, options)
+           options: JIterable[SocketOption]): Command = Bind(handler, endpoint, backlog, options)
   def bind(handler: ActorRef,
            endpoint: InetSocketAddress,
-           backlog: Int) = Bind(handler, endpoint, backlog, Nil)
+           backlog: Int): Command = Bind(handler, endpoint, backlog, Nil)
 
-  def register(handler: ActorRef) = Register(handler)
+  def register(handler: ActorRef): Command = Register(handler)
-  def unbind = Unbind
+  def unbind: Command = Unbind
 
-  def close = Close
+  def close: Command = Close
-  def confirmedClose = ConfirmedClose
+  def confirmedClose: Command = ConfirmedClose
-  def abort = Abort
+  def abort: Command = Abort
 
-  def noAck = NoAck
+  def noAck: NoAck = NoAck
-  def noAck(token: AnyRef) = NoAck(token)
+  def noAck(token: AnyRef): NoAck = NoAck(token)
 
-  def write(data: ByteString) = Write(data)
+  def write(data: ByteString): Command = Write(data)
-  def write(data: ByteString, ack: AnyRef) = Write(data, ack)
+  def write(data: ByteString, ack: AnyRef): Command = Write(data, ack)
 
-  def stopReading = StopReading
+  def stopReading: Command = StopReading
-  def resumeReading = ResumeReading
+  def resumeReading: Command = ResumeReading
 
   implicit private def fromJava[T](coll: JIterable[T]): immutable.Traversable[T] = {
     import scala.collection.JavaConverters._

akka-actor/src/main/scala/akka/io/TcpConnection.scala

@@ -20,6 +20,8 @@ import akka.io.SelectionHandler._
 
 /**
  * Base class for TcpIncomingConnection and TcpOutgoingConnection.
+ *
+ * INTERNAL API
  */
 private[io] abstract class TcpConnection(val channel: SocketChannel,
                                          val tcp: TcpExt) extends Actor with ActorLogging {
@@ -298,6 +300,9 @@ private[io] abstract class TcpConnection(val channel: SocketChannel,
   }
 }
 
+/**
+ * INTERNAL API
+ */
 private[io] object TcpConnection {
   sealed trait ReadResult
   object NoData extends ReadResult

akka-actor/src/main/scala/akka/io/TcpIncomingConnection.scala

@@ -13,6 +13,8 @@ import akka.io.SelectionHandler.{ ChannelRegistered, RegisterChannel }
 /**
  * An actor handling the connection state machine for an incoming, already connected
  * SocketChannel.
+ *
+ * INTERNAL API
  */
 private[io] class TcpIncomingConnection(_channel: SocketChannel,
                                         _tcp: TcpExt,

akka-actor/src/main/scala/akka/io/TcpListener.scala

@@ -15,6 +15,9 @@ import akka.io.Inet.SocketOption
 import akka.io.Tcp._
 import akka.io.IO.HasFailureMessage
 
+/**
+ * INTERNAL API
+ */
 private[io] object TcpListener {
 
   case class RegisterIncoming(channel: SocketChannel) extends HasFailureMessage {
@@ -25,6 +28,9 @@ private[io] object TcpListener {
 
 }
 
+/**
+ * INTERNAL API
+ */
 private[io] class TcpListener(val selectorRouter: ActorRef,
                               val tcp: TcpExt,
                               val bindCommander: ActorRef,

akka-actor/src/main/scala/akka/io/TcpManager.scala

@@ -9,6 +9,8 @@ import akka.actor.{ ActorLogging, Props }
 import akka.io.IO.SelectorBasedManager
 
 /**
+ * INTERNAL API
+ *
  * TcpManager is a facade for accepting commands ([[akka.io.Tcp.Command]]) to open client or server TCP connections.
  *
  * TcpManager is obtainable by calling {{{ IO(Tcp) }}} (see [[akka.io.IO]] and [[akka.io.Tcp]])

akka-actor/src/main/scala/akka/io/TcpOutgoingConnection.scala

@@ -15,6 +15,8 @@ import scala.collection.immutable
 /**
  * An actor handling the connection state machine for an outgoing connection
  * to be established.
+ *
+ * INTERNAL API
  */
 private[io] class TcpOutgoingConnection(_tcp: TcpExt,
                                         commander: ActorRef,
@@ -53,7 +55,10 @@ private[io] class TcpOutgoingConnection(_tcp: TcpExt,
 
 }
 
-object TcpOutgoingConnection {
+/**
+ * INTERNAL API
+ */
+private[io] object TcpOutgoingConnection {
   private def newSocketChannel() = {
     val channel = SocketChannel.open()
     channel.configureBlocking(false)

akka-actor/src/main/scala/akka/io/UdpConnManager.scala

@@ -7,7 +7,10 @@ import akka.actor.Props
 import akka.io.IO.SelectorBasedManager
 import akka.io.UdpConn.Connect
 
-class UdpConnManager(udpConn: UdpConnExt) extends SelectorBasedManager(udpConn.settings, udpConn.settings.NrOfSelectors) {
+/**
+ * INTERNAL API
+ */
+private[io] class UdpConnManager(udpConn: UdpConnExt) extends SelectorBasedManager(udpConn.settings, udpConn.settings.NrOfSelectors) {
 
   def receive = workerForCommandHandler {
     case c: Connect ⇒

akka-actor/src/main/scala/akka/io/UdpConnection.scala

@@ -13,6 +13,9 @@ import java.nio.channels.SelectionKey._
 import scala.annotation.tailrec
 import scala.util.control.NonFatal
 
+/**
+ * INTERNAL API
+ */
 private[io] class UdpConnection(val udpConn: UdpConnExt,
                                 val commander: ActorRef,
                                 val connect: Connect) extends Actor with ActorLogging {

akka-actor/src/main/scala/akka/io/UdpFFListener.scala

@@ -14,6 +14,9 @@ import java.nio.channels.SelectionKey._
 import scala.annotation.tailrec
 import scala.util.control.NonFatal
 
+/**
+ * INTERNAL API
+ */
 private[io] class UdpFFListener(val udpFF: UdpFFExt,
                                 val bindCommander: ActorRef,
                                 val bind: Bind)

akka-actor/src/main/scala/akka/io/UdpFFManager.scala

@@ -8,6 +8,8 @@ import akka.io.IO.SelectorBasedManager
 import akka.io.UdpFF._
 
 /**
+ * INTERNAL API
+ *
  * UdpFFManager is a facade for simple fire-and-forget style UDP operations
  *
  * UdpFFManager is obtainable by calling {{{ IO(UdpFF) }}} (see [[akka.io.IO]] and [[akka.io.UdpFF]])

akka-actor/src/main/scala/akka/io/UdpFFSender.scala

@@ -13,6 +13,8 @@ import scala.util.control.NonFatal
 
 /**
  * Base class for TcpIncomingConnection and TcpOutgoingConnection.
+ *
+ * INTERNAL API
  */
 private[io] class UdpFFSender(val udpFF: UdpFFExt, options: immutable.Traversable[SocketOption], val commander: ActorRef)
   extends Actor with ActorLogging with WithUdpFFSend {

akka-actor/src/main/scala/akka/io/WithUdpFFSend.scala

@@ -8,6 +8,9 @@ import akka.io.UdpFF.{ CommandFailed, Send }
 import akka.io.SelectionHandler._
 import java.nio.channels.DatagramChannel
 
+/**
+ * INTERNAL API
+ */
 private[io] trait WithUdpFFSend {
   me: Actor with ActorLogging ⇒
 

akka-docs/rst/java/code/docs/io/IODocTest.java

@@ -87,13 +87,5 @@ public class IODocTest {
 
   static ActorSystem system;
 
-  @BeforeClass
+  // This is currently only a compilation test, nothing is run
-  static public void setup() {
-    system = ActorSystem.create("IODocTest");
-  }
-
-  @Test
-  public void demonstrateConnect() {
-  }
-
 }