Moved C++ comments from source files to headers (#1111)

Also sorted functions in C++ sources to match order in related headers.

wpilibc/src/main/native/cpp/SerialPort.cpp

@@ -15,17 +15,6 @@
 
 using namespace frc;
 
-/**
- * Create an instance of a Serial Port class.
- *
- * @param baudRate The baud rate to configure the serial port.
- * @param port     The physical port to use
- * @param dataBits The number of data bits per transfer.  Valid values are
- *                 between 5 and 8 bits.
- * @param parity   Select the type of parity checking to use.
- * @param stopBits The number of stop bits to use as defined by the enum
- *                 StopBits.
- */
 SerialPort::SerialPort(int baudRate, Port port, int dataBits,
                        SerialPort::Parity parity,
                        SerialPort::StopBits stopBits) {
@@ -61,18 +50,6 @@ SerialPort::SerialPort(int baudRate, Port port, int dataBits,
   HAL_Report(HALUsageReporting::kResourceType_SerialPort, 0);
 }
 
-/**
- * Create an instance of a Serial Port class.
- *
- * @param baudRate The baud rate to configure the serial port.
- * @param port     The physical port to use
- * @param portName The direct port name to use
- * @param dataBits The number of data bits per transfer.  Valid values are
- *                 between 5 and 8 bits.
- * @param parity   Select the type of parity checking to use.
- * @param stopBits The number of stop bits to use as defined by the enum
- *                 StopBits.
- */
 SerialPort::SerialPort(int baudRate, const wpi::Twine& portName, Port port,
                        int dataBits, SerialPort::Parity parity,
                        SerialPort::StopBits stopBits) {
@@ -112,20 +89,12 @@ SerialPort::SerialPort(int baudRate, const wpi::Twine& portName, Port port,
   HAL_Report(HALUsageReporting::kResourceType_SerialPort, 0);
 }
 
-/**
- * Destructor.
- */
 SerialPort::~SerialPort() {
   int32_t status = 0;
   HAL_CloseSerial(static_cast<HAL_SerialPort>(m_port), &status);
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Set the type of flow control to enable on this port.
- *
- * By default, flow control is disabled.
- */
 void SerialPort::SetFlowControl(SerialPort::FlowControl flowControl) {
   int32_t status = 0;
   HAL_SetSerialFlowControl(static_cast<HAL_SerialPort>(m_port), flowControl,
@@ -133,15 +102,6 @@ void SerialPort::SetFlowControl(SerialPort::FlowControl flowControl) {
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Enable termination and specify the termination character.
- *
- * Termination is currently only implemented for receive.
- * When the the terminator is recieved, the Read() or Scanf() will return
- * fewer bytes than requested, stopping after the terminator.
- *
- * @param terminator The character to use for termination.
- */
 void SerialPort::EnableTermination(char terminator) {
   int32_t status = 0;
   HAL_EnableSerialTermination(static_cast<HAL_SerialPort>(m_port), terminator,
@@ -149,20 +109,12 @@ void SerialPort::EnableTermination(char terminator) {
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Disable termination behavior.
- */
 void SerialPort::DisableTermination() {
   int32_t status = 0;
   HAL_DisableSerialTermination(static_cast<HAL_SerialPort>(m_port), &status);
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Get the number of bytes currently available to read from the serial port.
- *
- * @return The number of bytes available to read
- */
 int SerialPort::GetBytesReceived() {
   int32_t status = 0;
   int retVal =
@@ -171,13 +123,6 @@ int SerialPort::GetBytesReceived() {
   return retVal;
 }
 
-/**
- * Read raw bytes out of the buffer.
- *
- * @param buffer Pointer to the buffer to store the bytes in.
- * @param count  The maximum number of bytes to read.
- * @return The number of bytes actually read into the buffer.
- */
 int SerialPort::Read(char* buffer, int count) {
   int32_t status = 0;
   int retVal = HAL_ReadSerial(static_cast<HAL_SerialPort>(m_port), buffer,
@@ -186,26 +131,10 @@ int SerialPort::Read(char* buffer, int count) {
   return retVal;
 }
 
-/**
- * Write raw bytes to the buffer.
- *
- * @param buffer Pointer to the buffer to read the bytes from.
- * @param count  The maximum number of bytes to write.
- * @return The number of bytes actually written into the port.
- */
 int SerialPort::Write(const char* buffer, int count) {
   return Write(wpi::StringRef(buffer, static_cast<size_t>(count)));
 }
 
-/**
- * Write raw bytes to the buffer.
- *
- * Use Write({data, len}) to get a buffer that is shorter than the length of the
- * string.
- *
- * @param buffer StringRef to the buffer to read the bytes from.
- * @return The number of bytes actually written into the port.
- */
 int SerialPort::Write(wpi::StringRef buffer) {
   int32_t status = 0;
   int retVal = HAL_WriteSerial(static_cast<HAL_SerialPort>(m_port),
@@ -214,32 +143,12 @@ int SerialPort::Write(wpi::StringRef buffer) {
   return retVal;
 }
 
-/**
- * Configure the timeout of the serial port.
- *
- * This defines the timeout for transactions with the hardware.
- * It will affect reads and very large writes.
- *
- * @param timeout The number of seconds to to wait for I/O.
- */
 void SerialPort::SetTimeout(double timeout) {
   int32_t status = 0;
   HAL_SetSerialTimeout(static_cast<HAL_SerialPort>(m_port), timeout, &status);
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Specify the size of the input buffer.
- *
- * Specify the amount of data that can be stored before data
- * from the device is returned to Read or Scanf.  If you want
- * data that is recieved to be returned immediately, set this to 1.
- *
- * It the buffer is not filled before the read timeout expires, all
- * data that has been received so far will be returned.
- *
- * @param size The read buffer size.
- */
 void SerialPort::SetReadBufferSize(int size) {
   int32_t status = 0;
   HAL_SetSerialReadBufferSize(static_cast<HAL_SerialPort>(m_port), size,
@@ -247,14 +156,6 @@ void SerialPort::SetReadBufferSize(int size) {
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Specify the size of the output buffer.
- *
- * Specify the amount of data that can be stored before being
- * transmitted to the device.
- *
- * @param size The write buffer size.
- */
 void SerialPort::SetWriteBufferSize(int size) {
   int32_t status = 0;
   HAL_SetSerialWriteBufferSize(static_cast<HAL_SerialPort>(m_port), size,
@@ -262,40 +163,18 @@ void SerialPort::SetWriteBufferSize(int size) {
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Specify the flushing behavior of the output buffer.
- *
- * When set to kFlushOnAccess, data is synchronously written to the serial port
- * after each call to either Printf() or Write().
- *
- * When set to kFlushWhenFull, data will only be written to the serial port when
- * the buffer is full or when Flush() is called.
- *
- * @param mode The write buffer mode.
- */
 void SerialPort::SetWriteBufferMode(SerialPort::WriteBufferMode mode) {
   int32_t status = 0;
   HAL_SetSerialWriteMode(static_cast<HAL_SerialPort>(m_port), mode, &status);
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Force the output buffer to be written to the port.
- *
- * This is used when SetWriteBufferMode() is set to kFlushWhenFull to force a
- * flush before the buffer is full.
- */
 void SerialPort::Flush() {
   int32_t status = 0;
   HAL_FlushSerial(static_cast<HAL_SerialPort>(m_port), &status);
   wpi_setErrorWithContext(status, HAL_GetErrorMessage(status));
 }
 
-/**
- * Reset the serial port driver to a known state.
- *
- * Empty the transmit and receive buffers in the device and formatted I/O.
- */
 void SerialPort::Reset() {
   int32_t status = 0;
   HAL_ClearSerial(static_cast<HAL_SerialPort>(m_port), &status);