Index: ossp-pkg/sa/sa.h
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.h,v
rcsdiff -q -kk '-r1.7' '-r1.8' -u '/v/ossp/cvs/ossp-pkg/sa/sa.h,v' 2>/dev/null
--- sa.h	2001/10/05 20:52:15	1.7
+++ sa.h	2001/10/05 21:11:22	1.8
@@ -95,7 +95,7 @@
 
 /* return codes */
 typedef enum {
-    SA_OK,
+    SA_OK,      /* everything ok */
     SA_ERR_ARG, /* invalid argument (wrong parameter) */
     SA_ERR_USE, /* invalid use (wrong context) */
     SA_ERR_MEM, /* out of memory */
Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.6' '-r1.7' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2001/10/05 20:52:15	1.6
+++ sa.pod	2001/10/05 21:11:22	1.7
@@ -39,9 +39,9 @@
 
 =item B<Abstract Data Types>:
 
+sa_rc_t,
 sa_addr_t,
-sa_t,
-sa_rc_t.
+sa_t.
 
 =item B<Address Object Operations>:
 
@@ -93,22 +93,23 @@
 
 =head1 DESCRIPTION
 
-B<OSSP sa> is a thin abstraction library for the BSD socket interface
-for use in conjunction with TCP and UDP protocols. It provides the
-following key features:
+B<OSSP sa> is an abstraction library for the Unix socket interface
+featuring stream and datagram oriented communication over Unix Domain
+and Internet Domain sockets.
+
+It provides the following key features:
 
 =over 4
 
 =item B<Address Abstraction>
 
-Most of the uglyness in the BSD socket API is the necessarity to have to
-deal with the various address structures (C<struct sockaddr_xx>) which
-exist because of both the different network protocols and addressing
-schemes. B<OSSP sa> fully hides this by providing an abstract and
-opaque address type (C<sa_addr_t>) together with four utility functions
-which allow one to convert from the old C<struct sockaddr> and an URL
-specification (C<{tcp,udp}://<host>[:<port>]>) to the C<sa_addr_t> and
-vice versa.
+Most of the uglyness in the Unix socket API is the necessarity to have
+to deal with the various address structures (C<struct sockaddr_xx>)
+which exist because of both the different communication types and
+addressing schemes. B<OSSP sa> fully hides this by providing an abstract
+and opaque address type (C<sa_addr_t>) together with four utility
+functions which allow one to convert from the traditional C<struct
+sockaddr> or URI specification to the C<sa_addr_t> and vice versa.
 
 =item B<Type Abstraction>
 
@@ -123,36 +124,51 @@
 
 =item B<I/O Timeouts>
 
-Each function of B<OSSP sa> is aware of a central timeout (set by
-sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_SYS> and
-C<errno> set to C<ETIMEDOUT> if this timeout expired before the
+Each I/O function in B<OSSP sa> is aware of a central timeout (set
+by sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_SYS>
+and C<errno> set to C<ETIMEDOUT> if this timeout expired before the
 operation was able to succeed. This allows one to easily program
 less-blocking network services.
 
 =item B<Buffered I/O>
 
-If B<OSSP sa> is used for TCP-based stream I/O, internally all I/O
-operations can be performed through input and output buffers (set
+If B<OSSP sa> is used for stream communication, internally all I/O
+operations can be performed through input and/or output buffers (set
 by sa_buffers(3)) for achieving higher I/O performance by doing I/O
-operations on larger messages.
+operations on larger aggregated messages.
 
 =item B<Convinience I/O Functions>
 
-If B<OSSP sa> is used for TCP-based stream I/O, for convinience reasons
-line reading (sa_readline(3)) and output formatting (sa_writef(3))
-functions are provided, modelled after STDIO's fgets(3) and fprintf(3).
+If B<OSSP sa> is used for stream communication, for convinience reasons
+line-oriented reading (sa_readln(3)) and formated writing (sa_writef(3))
+is provided, modelled after STDIO's fgets(3) and fprintf(3).
 
 =back
 
 =head1 DATA TYPES
 
+B<OSSP sa> uses three data types in its API:
+
 =over 4
 
-=item B<sa_addr_t>
+=item B<sa_rc_t> (Return Code Type)
+
+This is an exported enumerated integer type with the following possible
+values: C<SA_OK> (everything ok, operation succeeded); C<SA_ERR_ARG>
+(invalid argument(s) passed to function); C<SA_ERR_USE> (function used
+in wrong context); C<SA_ERR_MEM> (out of memory); C<SA_ERR_EOF> (end of
+file/socket in communication); C<SA_ERR_SYS> (operating system error;
+errno contains details); C<SA_ERR_INT> (any other internal error).
+
+=item B<sa_addr_t> (Socket Address Abstraction Type)
+
+This is an opaque type representing a socket address. 
+Only pointers to this abstract type are used in the API.
 
-=item B<sa_t>
+=item B<sa_t> (Socket Abstraction Type)
 
-=item B<sa_rc_tt>
+This is an opaque type representing a socket.
+Only pointers to this abstract type are used in the API.
 
 =back