Minor Doxygen improvements and fixes.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 472c1d078d6031bc1f1e3a1c59a5250ab75d7eff..44c6684fb11bf07fd9330770f148f52ec1c7d67d 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -95,12 +95,12 @@ enum sp_return {
        SP_OK = 0,
        /** Invalid arguments were passed to the function. */
        SP_ERR_ARG = -1,
-       /** A system error occured while executing the operation. */
+       /** A system error occurred while executing the operation. */
        SP_ERR_FAIL = -2,
        /** A memory allocation failed while executing the operation. */
        SP_ERR_MEM = -3,
        /** The requested operation is not supported by this system or device. */
-       SP_ERR_SUPP = -4,
+       SP_ERR_SUPP = -4
 };
 
 /** Port access modes. */
@@ -109,16 +109,18 @@ enum sp_mode {
        SP_MODE_READ = 1,
        /** Open port for write access. */
        SP_MODE_WRITE = 2,
+       /** Open port for read and write access. */
+       SP_MODE_READ_WRITE = 3
 };
 
 /** Port events. */
 enum sp_event {
-       /* Data received and ready to read. */
+       /** Data received and ready to read. */
        SP_EVENT_RX_READY = 1,
-       /* Ready to transmit new data. */
+       /** Ready to transmit new data. */
        SP_EVENT_TX_READY = 2,
-       /* Error occured. */
-       SP_EVENT_ERROR = 4,
+       /** Error occurred. */
+       SP_EVENT_ERROR = 4
 };
 
 /** Buffer selection. */
@@ -128,7 +130,7 @@ enum sp_buffer {
        /** Output buffer. */
        SP_BUF_OUTPUT = 2,
        /** Both buffers. */
-       SP_BUF_BOTH = 3,
+       SP_BUF_BOTH = 3
 };
 
 /** Parity settings. */
@@ -144,7 +146,7 @@ enum sp_parity {
        /** Mark parity. */
        SP_PARITY_MARK = 3,
        /** Space parity. */
-       SP_PARITY_SPACE = 4,
+       SP_PARITY_SPACE = 4
 };
 
 /** RTS pin behaviour. */
@@ -156,7 +158,7 @@ enum sp_rts {
        /** RTS on. */
        SP_RTS_ON = 1,
        /** RTS used for flow control. */
-       SP_RTS_FLOW_CONTROL = 2,
+       SP_RTS_FLOW_CONTROL = 2
 };
 
 /** CTS pin behaviour. */
@@ -166,7 +168,7 @@ enum sp_cts {
        /** CTS ignored. */
        SP_CTS_IGNORE = 0,
        /** CTS used for flow control. */
-       SP_CTS_FLOW_CONTROL = 1,
+       SP_CTS_FLOW_CONTROL = 1
 };
 
 /** DTR pin behaviour. */
@@ -178,7 +180,7 @@ enum sp_dtr {
        /** DTR on. */
        SP_DTR_ON = 1,
        /** DTR used for flow control. */
-       SP_DTR_FLOW_CONTROL = 2,
+       SP_DTR_FLOW_CONTROL = 2
 };
 
 /** DSR pin behaviour. */
@@ -188,7 +190,7 @@ enum sp_dsr {
        /** DSR ignored. */
        SP_DSR_IGNORE = 0,
        /** DSR used for flow control. */
-       SP_DSR_FLOW_CONTROL = 1,
+       SP_DSR_FLOW_CONTROL = 1
 };
 
 /** XON/XOFF flow control behaviour. */
@@ -202,7 +204,7 @@ enum sp_xonxoff {
        /** XON/XOFF enabled for output only. */
        SP_XONXOFF_OUT = 2,
        /** XON/XOFF enabled for input and output. */
-       SP_XONXOFF_INOUT = 3,
+       SP_XONXOFF_INOUT = 3
 };
 
 /** Standard flow control combinations. */
@@ -214,7 +216,7 @@ enum sp_flowcontrol {
        /** Hardware flow control using RTS/CTS signals. */
        SP_FLOWCONTROL_RTSCTS = 2,
        /** Hardware flow control using DTR/DSR signals. */
-       SP_FLOWCONTROL_DTRDSR = 3,
+       SP_FLOWCONTROL_DTRDSR = 3
 };
 
 /** Input signals. */
@@ -226,7 +228,7 @@ enum sp_signal {
        /** Data carrier detect. */
        SP_SIG_DCD = 4,
        /** Ring indicator. */
-       SP_SIG_RI = 8,
+       SP_SIG_RI = 8
 };
 
 /** Transport types. */
@@ -235,8 +237,8 @@ enum sp_transport {
        SP_TRANSPORT_NATIVE,
        /** USB serial port adapter. */
        SP_TRANSPORT_USB,
-       /** Bluetooh serial port adapter. */
-       SP_TRANSPORT_BLUETOOTH,
+       /** Bluetooth serial port adapter. */
+       SP_TRANSPORT_BLUETOOTH
 };
 
 /**
@@ -265,9 +267,12 @@ struct sp_event_set {
 };
 
 /**
-@defgroup Enumeration Port enumeration
-@{
-*/
+ * @defgroup Enumeration Port enumeration
+ *
+ * Enumerating the serial ports of a system.
+ *
+ * @{
+ */
 
 /**
  * Obtain a pointer to a new sp_port structure representing the named port.
@@ -342,7 +347,10 @@ void sp_free_port_list(struct sp_port **ports);
 
 /**
  * @}
- * @defgroup Ports Opening, closing and querying ports
+ * @defgroup Ports Port handling
+ *
+ * Opening, closing and querying ports.
+ *
  * @{
  */
 
@@ -515,7 +523,10 @@ enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
 
 /**
  * @}
- * @defgroup Configuration Setting port parameters
+ *
+ * @defgroup Configuration Configuration
+ *
+ * Setting and querying serial port parameters.
  * @{
  */
 
@@ -966,9 +977,13 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow
 
 /**
  * @}
- * @defgroup Data Reading, writing, and flushing data
+ *
+ * @defgroup Data Data handling
+ *
+ * Reading, writing, and flushing data.
+ *
  * @{
-*/
+ */
 
 /**
  * Read bytes from the specified serial port, blocking until complete.
@@ -1043,7 +1058,7 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count
  *         written. If timeout is zero, the function will always return
  *         either the requested number of bytes or a negative error code. In
  *         the event of an error there is no way to determine how many bytes
- *         were sent before the error occured.
+ *         were sent before the error occurred.
  *
  * @since 0.1.0
  */
@@ -1124,7 +1139,11 @@ enum sp_return sp_drain(struct sp_port *port);
 
 /**
  * @}
- * @defgroup Waiting Waiting for events
+ *
+ * @defgroup Waiting Waiting
+ *
+ * Waiting for events and timeout handling.
+ *
  * @{
  */
 
@@ -1183,7 +1202,11 @@ void sp_free_event_set(struct sp_event_set *event_set);
 
 /**
  * @}
- * @defgroup Signals Port signalling operations
+ *
+ * @defgroup Signals Signals
+ *
+ * Port signalling operations.
+ *
  * @{
  */
 
@@ -1196,13 +1219,13 @@ void sp_free_event_set(struct sp_event_set *event_set);
  * the sp_signal enum.
  *
  * @param port Pointer to port structure.
- * @param signals Pointer to variable to receive result.
+ * @param signal_mask Pointer to variable to receive result.
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
  * @since 0.1.0
  */
-enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signals);
+enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask);
 
 /**
  * Put the port transmit line into the break state.
@@ -1228,9 +1251,13 @@ enum sp_return sp_end_break(struct sp_port *port);
 
 /**
  * @}
- * @defgroup Errors Obtaining error information
+ *
+ * @defgroup Errors Errors
+ *
+ * Obtaining error information.
+ *
  * @{
-*/
+ */
 
 /**
  * Get the error code for a failed operation.
@@ -1296,7 +1323,9 @@ void sp_default_debug_handler(const char *format, ...);
 /** @} */
 
 /**
- * @defgroup Versions Version number querying functions, definitions, and macros
+ * @defgroup Versions Versions
+ *
+ * Version number querying functions, definitions, and macros.
  *
  * This set of API calls returns two different version numbers related
  * to libserialport. The "package version" is the release version number of the