From: Martin Ling <redacted>
Date: Sun, 3 Nov 2013 22:30:46 +0000 (+0000)
Subject: Update documentation.
X-Git-Tag: libserialport-0.1.0~146
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=016193288478dd146b8aec2f8d14945ccd4bd2aa;p=libserialport.git

Update documentation.
---

diff --git a/README b/README
index 50cb7b2..2bd7fea 100644
--- a/README
+++ b/README
@@ -67,7 +67,7 @@ port. This structure is obtained from the array returned by sp_list_ports().
 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
 OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed.
-Aoth these error values are negative.
+All of these error values are negative.
 
 When SP_ERR_FAIL is returned, an error code or string description of the error
 can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
@@ -82,15 +82,36 @@ The available functions are as follows:
 Enumeration
 -----------
 
-struct sp_port **sp_list_ports();
+int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
 
- Lists the serial ports available on the system. The value returned is an array
- of pointers to sp_port structures, terminated by a NULL. It should be freed after
- use by calling sp_free_port_list().
+ Obtains a pointer to a new sp_port structure representing the named port. The
+ user should allocate a variable of type "struct sp_port *" and pass a pointer
+ to this to receive the result.
+ 
+ Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure,
+          or SP_ERR_ARG if an invalid pointer is passed. If any error is returned,
+          the value pointed to by port_ptr will be set to NULL.
+
+void sp_free_port(struct sp_port *port);
+
+ Frees a port structure obtained from sp_get_port_by_name().
+
+int sp_list_ports(struct sp_port ***list_ptr);
+
+ Lists the serial ports available on the system. The result obtained is an
+ array of pointers to sp_port structures, terminated by a NULL. The user should
+ allocate a variable of type "struct sp_port **" and pass a pointer to this to
+ receive the result.
+
+ The result should be freed after use by calling sp_free_port_list().
+
+ Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure,
+          or SP_ERR_ARG if an invalid pointer is passed. If any error is returned,
+          the value pointed to by list_ptr will be set to NULL.
 
 void sp_free_port_list(struct sp_port **list);
 
- Frees the data structure returned by sp_list_ports().
+ Frees a port list obtained from sp_list_ports().
 
 Opening and closing ports
 -------------------------
@@ -106,7 +127,7 @@ int sp_open(struct sp_port *port, int flags);
              flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
 
  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
-          if an invalid port or name is passed.
+          if an invalid port is passed.
 
 int sp_close(struct sp_port *port);