From: Martin Ling <redacted>
Date: Tue, 19 Nov 2013 03:14:09 +0000 (+0000)
Subject: Clarify usage of -1 in configuration API.
X-Git-Tag: libserialport-0.1.0~101
X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=commitdiff_plain;h=c200f5c1449bd3a82f166f8243e08a41530db3d1

Clarify usage of -1 in configuration API.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 5a1c0ae..06058c2 100644
--- 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.