Clarify usage of -1 in configuration API.

diff --git a/libserialport.h.in b/libserialport.h.in
index 5a1c0aecd511ad0ee067aa3cb932485c40d7addc..06058c25253c13d3f7412d75ff6bfc837e838cd6 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -112,6 +112,7 @@ enum sp_mode {
 
 /** Parity settings. */
 enum sp_parity {
+       /** Special value to indicate setting should be left alone. */
        SP_PARITY_INVALID = -1,
        /** No parity. */
        SP_PARITY_NONE = 0,
@@ -123,6 +124,7 @@ enum sp_parity {
 
 /** RTS pin behaviour. */
 enum sp_rts {
+       /** Special value to indicate setting should be left alone. */
        SP_RTS_INVALID = -1,
        /** RTS off. */
        SP_RTS_OFF = 0,
@@ -134,6 +136,7 @@ enum sp_rts {
 
 /** CTS pin behaviour. */
 enum sp_cts {
+       /** Special value to indicate setting should be left alone. */
        SP_CTS_INVALID = -1,
        /** CTS ignored. */
        SP_CTS_IGNORE = 0,
@@ -143,6 +146,7 @@ enum sp_cts {
 
 /** DTR pin behaviour. */
 enum sp_dtr {
+       /** Special value to indicate setting should be left alone. */
        SP_DTR_INVALID = -1,
        /** DTR off. */
        SP_DTR_OFF = 0,
@@ -154,6 +158,7 @@ enum sp_dtr {
 
 /** DSR pin behaviour. */
 enum sp_dsr {
+       /** Special value to indicate setting should be left alone. */
        SP_DSR_INVALID = -1,
        /** DSR ignored. */
        SP_DSR_IGNORE = 0,
@@ -163,6 +168,7 @@ enum sp_dsr {
 
 /** XON/XOFF flow control behaviour. */
 enum sp_xonxoff {
+       /** Special value to indicate setting should be left alone. */
        SP_XONXOFF_INVALID = -1,
        /** XON/XOFF disabled. */
        SP_XONXOFF_DISABLED = 0,
@@ -321,19 +327,21 @@ enum sp_return sp_close(struct sp_port *port);
  as the config parameter. The struct will be populated with the port
  configuration.
 
+ Any setting that is in a state not recognised or supported by
+ libserialport will have its value set to -1 in the struct.
+
  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
           for invalid arguments.
 */
 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
 
 /**
- Sets all parameters for the specified serial port.
+ Sets configuration for the specified serial port.
 
  The user should populate a struct sp_port_config, then pass a pointer to it
  as the config parameter.
 
- To retain the current value of any setting, set the field to to a
- negative value.
+ To retain the current value of any setting, set that field to -1.
 
  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
           for invalid arguments.