add documentation

4 files changed, 74 insertions, 19 deletions

diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala
index bff0ad0..adcfb06 100644
--- a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala
+++ b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala
@@ -7,19 +7,72 @@ import akka.util.ByteString
 /** Defines messages used by serial IO layer. */
 object Serial extends ExtensionKey[SerialExt] {
 
+  /** A message extending this trait is to be viewed as a command, that is an outbound message. */
   trait Command
+
+  /** A message extending this trait is to be viewed as an event, that is an inbound message. */
   trait Event
-  
+
+  /**
+   * Open a new serial port. Send this command to the serial manager to request the opening of a new port.
+   * @param handler actor that will receive events from the specified serial port
+   * @param port name of serial port
+   * @param baud baud rate to use with serial port
+   * @param characterSize size of a character of the data sent through the serial port
+   * @param twoStopBits set to use two stop bits instead of one
+   * @param parity type of parity to use with serial port
+   */
   case class Open(handler: ActorRef, port: String, baud: Int, characterSize: Int = 8, twoStopBits: Boolean = false, parity: Parity.Parity = Parity.None) extends Command
-  case class Opened(port: String) extends Event
-  case class OpenFailed(port: String, reason: Throwable) extends Event
-  
+
+  /**
+   * Event sent from a port operator, indicating that a serial port was successfully opened.
+   * @param port name of serial port
+   * @param baud baud rate to use with serial port
+   * @param characterSize size of a character of the data sent through the serial port
+   * @param twoStopBits set to use two stop bits instead of one
+   * @param parity type of parity to use with serial port
+   */
+  case class Opened(port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Parity.Parity) extends Event
+
+  /**
+   * Event sent from manager, indicating that a serial port could not be opened.
+   * @param reason throwable containing reason to why the requested port could not be opened
+   * @param port name of serial port
+   * @param baud baud rate to use with serial port
+   * @param characterSize size of a character of the data sent through the serial port
+   * @param twoStopBits set to use two stop bits instead of one
+   * @param parity type of parity to use with serial port
+   */
+  case class OpenFailed(reason: Throwable, port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Parity.Parity) extends Event
+
+  /**
+   * Event sent by operator, indicating that data was received from the operator's serial port.
+   * @param data data received by port
+   */
   case class Received(data: ByteString) extends Event
-  
+
+  /**
+   * Command sent to operator, requesting the writing of data to the operator's serial port. Optionally request acknowledgment when data is written.
+   * @param data data to be written to port
+   * @param ack set to true to receive acknowledgment on successful write
+   * @see Wrote
+   */
   case class Write(data: ByteString, ack: Boolean = false) extends Command
+
+  /**
+   * Event sent by operator, acknowledging that data was written to its serial port. Note that such an acknowledgment only guarantees that data has been written
+   * to the serial port's output buffer (managed by the operating system), the actual reception of the data on the remote device is not guaranteed.
+   * @param data the data that has been written
+   */
   case class Wrote(data: ByteString) extends Event
-  
+
+  /** Command sent to operator to request the closing of its serial port. */
   case object Close extends Command
-  case class Closed(error: Option[Exception]) extends Event
-  
+
+  /**
+   * Event sent from operator, indicating that its port has been closed. An optional reason explains the error that caused the closing of the port.
+   * @param reason Some(exception) explaining the exception that caused the closing, None if the port was closed by sending a `Close` message.
+   */
+  case class Closed(reason: Option[Exception]) extends Event
+
 }
diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala b/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala
index 1a38ef5..1f32ecd 100644
--- a/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala
+++ b/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala
@@ -32,7 +32,7 @@ class SerialManager extends Actor with ActorLogging {
     case Open(handler, port, baud, cs, tsb, parity) => Try { InternalSerial.open(port, baud, cs, tsb, parity.id) } match {
       case Failure(t) => {
         log.debug(s"failed to open low serial port at ${port}, baud ${baud}, reason: " + t.getMessage())
-        handler ! OpenFailed(port, t)
+        handler ! OpenFailed(t, port, baud, cs, tsb, parity)
       }
 
       case Success(serial) => {
diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala b/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala
index 604dc74..4e46343 100644
--- a/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala
+++ b/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala
@@ -50,16 +50,14 @@ class SerialOperator(handler: ActorRef, serial: InternalSerial) extends Actor wi
     
     override def run() {
       this.setName("flow-reader " + serial.port)
-      log.debug(name + ": started reader thread")
       enterReadLoop()
-      log.debug(name + ": exiting")
     }
     
   }
 
   override def preStart() = {
     context watch handler
-    handler ! Opened(serial.port)
+    handler ! Opened(serial.port, serial.baud, serial.characterSize, serial.twoStopBits, Parity(serial.parity))
     Reader.start()
   }
 
diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala b/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala
index fd5aaa4..c7752b2 100644
--- a/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala
+++ b/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala
@@ -5,13 +5,13 @@ import com.github.jodersky.flow._
 import java.util.concurrent.atomic.AtomicBoolean
 
 /** Wraps NativeSerial in a more object-oriented style, still quite low level. */
-class InternalSerial private (val port: String, private val pointer: Long) {
+class InternalSerial private (val port: String, val baud: Int, val characterSize: Int, val twoStopBits: Boolean, val parity: Int, private val pointer: Long) {
   import InternalSerial._
 
   private val reading = new AtomicBoolean(false)
   private val writing = new AtomicBoolean(false)
   private val closed = new AtomicBoolean(false)
-  
+
   /** Closes the underlying serial connection. Any threads blocking on read or write will return. */
   def close(): Unit = synchronized {
     if (!closed.get()) {
@@ -23,8 +23,10 @@ class InternalSerial private (val port: String, private val pointer: Long) {
     }
   }
 
-  /** Read data from underlying serial connection.
-   *  @throws PortInterruptedException if port is closed from another thread */
+  /**
+   * Read data from underlying serial connection.
+   * @throws PortInterruptedException if port is closed from another thread
+   */
   def read(): Array[Byte] = if (!closed.get) {
     reading.set(true)
     try {
@@ -41,8 +43,10 @@ class InternalSerial private (val port: String, private val pointer: Long) {
     throw new PortClosedException(s"port ${port} is already closed")
   }
 
-  /** Write data to underlying serial connection.
-   *  @throws PortInterruptedException if port is closed from another thread */
+  /**
+   * Write data to underlying serial connection.
+   * @throws PortInterruptedException if port is closed from another thread
+   */
   def write(data: Array[Byte]): Array[Byte] = if (!closed.get) {
     writing.set(true)
     try {
@@ -79,7 +83,7 @@ object InternalSerial {
   def open(port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Int): InternalSerial = synchronized {
     val pointer = new Array[Long](1)
     except(NativeSerial.open(port, baud, characterSize, twoStopBits, parity, pointer), port)
-    new InternalSerial(port, pointer(0))
+    new InternalSerial(port, baud, characterSize, twoStopBits, parity, pointer(0))
   }
 
   /** Set debugging for all serial connections. Debugging results in printing extra messages (from the native library) in case of errors. */