Consistently use the "@" notation for Doxygen tags.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 5a1c0aecd511ad0ee067aa3cb932485c40d7addc..275bcee8d301441c69c7625f6ea5567e0731b686 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -19,7 +19,7 @@
 
 /**
 
-\mainpage libserialport API
+@mainpage libserialport API
 
 Introduction
 ============
@@ -32,11 +32,11 @@ transparently on any platform supported by the library.
 
 The operations that are supported are:
 
-- \ref Enumeration (obtaining a list of serial ports on the system).
-- \ref Ports
-- \ref Configuration (baud rate, parity, etc)
-- \ref Data
-- \ref Errors
+- @ref Enumeration (obtaining a list of serial ports on the system).
+- @ref Ports
+- @ref Configuration (baud rate, parity, etc)
+- @ref Data
+- @ref Errors
 
 libserialport is an open source project released under the LGPL3+ license.
 
@@ -48,7 +48,7 @@ support in each OS.
 
 Most functions take a pointer to a struct sp_port, which represents a serial
 port. These structures are always allocated and freed by the library, using
-the functions in the \ref Enumeration "Enumeration" section.
+the functions in the @ref Enumeration "Enumeration" section.
 
 All functions can return only three possible error values. SP_ERR_ARG indicates
 the function was called with invalid arguments. SP_ERR_FAIL indicates that the
@@ -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,
@@ -190,14 +196,14 @@ enum sp_flowcontrol {
 struct sp_port {
        /** Name used to open the port */
        char *name;
-/** \cond 0 */
+/** @cond 0 */
        /* OS-specific port handle */
 #ifdef _WIN32
        HANDLE hdl;
 #else
        int fd;
 #endif
-/** \endcond */
+/** @endcond */
 };
 
 /** Configuration for a serial port. */
@@ -223,7 +229,7 @@ struct sp_port_config {
 };
 
 /**
-\defgroup Enumeration Port enumeration
+@defgroup Enumeration Port enumeration
 @{
 */
 
@@ -285,7 +291,7 @@ void sp_free_port_list(struct sp_port **ports);
 
 /**
  @}
-\defgroup Ports Opening & closing ports
+@defgroup Ports Opening & closing ports
 @{
 */
 
@@ -310,7 +316,7 @@ enum sp_return sp_close(struct sp_port *port);
 
 /**
  @}
-\defgroup Configuration Setting port parameters
+@defgroup Configuration Setting port parameters
 @{
 */
 
@@ -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.
@@ -344,7 +352,7 @@ enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *
  Sets the baud rate for the specified serial port.
 
  @param port Pointer to port structure.
- @param baud Baud rate in bits per second.
+ @param baudrate Baud rate in bits per second.
 
  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
           for invalid arguments.
@@ -457,7 +465,7 @@ enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
 
 /**
  @}
-\defgroup Data Reading, writing & flushing data
+@defgroup Data Reading, writing & flushing data
 @{
 */
 
@@ -499,7 +507,7 @@ enum sp_return sp_flush(struct sp_port *port);
 
 /**
  @}
-\defgroup Errors Obtaining error information
+@defgroup Errors Obtaining error information
 @{
 */