doc: clarify protocol-tag family/type/protocol return values

The family()/type()/protocol() members on the protocol tags returned
bare platform constants documented as "the protocol (0)", which read
as one entry in an unlisted corosio enumeration (#255).

Explain at the class level that these three members produce the
(family, type, protocol) triple passed to the OS socket() call and
that the values are platform-defined constants, and expand
local_stream/local_datagram protocol() to state that 0 selects the
default (and only) protocol rather than indexing a list. Clarify the
socket/acceptor type aliases across all four tags.

Documentation only; no API or behavior change.

Author: mvandeberg

include/boost/corosio/local_datagram.hpp

@@ -24,9 +24,10 @@ class local_datagram_socket;
     Identifies the local datagram protocol for parameterizing
     socket open() calls with a self-documenting type.
 
-    The family(), type(), and protocol() members are implemented
-    in the compiled library to avoid exposing platform socket
-    headers.
+    The family(), type(), and protocol() members return the
+    three integers passed to the operating system's socket()
+    call. Their values are platform-defined constants taken from
+    the system socket headers.
 
     @note Not available on Windows. Windows does not support
         AF_UNIX datagram sockets (SOCK_DGRAM).
@@ -36,16 +37,22 @@ class local_datagram_socket;
 class BOOST_COROSIO_DECL local_datagram
 {
 public:
-    /// Return the address family (AF_UNIX).
+    /// Return the address family, the platform's `AF_UNIX` constant.
     static int family() noexcept;
 
-    /// Return the socket type (SOCK_DGRAM).
+    /// Return the socket type, the platform's `SOCK_DGRAM` constant.
     static int type() noexcept;
 
-    /// Return the protocol (0).
+    /** Return the protocol number, always `0`.
+
+        A value of `0` directs the operating system to select the
+        default protocol for an `AF_UNIX` `SOCK_DGRAM` socket. It
+        is not an index into a list of protocols: Unix domain
+        datagram sockets have only one, so `0` is the sole valid value.
+    */
     static int protocol() noexcept;
 
-    /// The associated socket type.
+    /// The socket type to use with this protocol, @ref local_datagram_socket.
     using socket = local_datagram_socket;
 };
 

include/boost/corosio/local_stream.hpp

@@ -23,9 +23,10 @@ class local_stream_acceptor;
     socket and acceptor open() calls with a self-documenting
     type.
 
-    The family(), type(), and protocol() members are implemented
-    in the compiled library to avoid exposing platform socket
-    headers.
+    The family(), type(), and protocol() members return the
+    three integers passed to the operating system's socket()
+    call. Their values are platform-defined constants taken from
+    the system socket headers.
 
     @par Example
     @code
@@ -38,19 +39,25 @@ class local_stream_acceptor;
 class BOOST_COROSIO_DECL local_stream
 {
 public:
-    /// Return the address family (AF_UNIX).
+    /// Return the address family, the platform's `AF_UNIX` constant.
     static int family() noexcept;
 
-    /// Return the socket type (SOCK_STREAM).
+    /// Return the socket type, the platform's `SOCK_STREAM` constant.
     static int type() noexcept;
 
-    /// Return the protocol (0).
+    /** Return the protocol number, always `0`.
+
+        A value of `0` directs the operating system to select the
+        default protocol for an `AF_UNIX` `SOCK_STREAM` socket. It
+        is not an index into a list of protocols: Unix domain
+        stream sockets have only one, so `0` is the sole valid value.
+    */
     static int protocol() noexcept;
 
-    /// The associated socket type.
+    /// The socket type to use with this protocol, @ref local_stream_socket.
     using socket = local_stream_socket;
 
-    /// The associated acceptor type.
+    /// The acceptor type to use with this protocol, @ref local_stream_acceptor.
     using acceptor = local_stream_acceptor;
 };
 

include/boost/corosio/tcp.hpp

@@ -23,10 +23,11 @@ class tcp_acceptor;
     (IPv4 or IPv6). It is used to parameterize socket and acceptor
     `open()` calls with a self-documenting type.
 
-    The `family()`, `type()`, and `protocol()` members are
-    implemented in the compiled library to avoid exposing
-    platform socket headers. For an inline variant that includes
-    platform headers, use @ref native_tcp.
+    The `family()`, `type()`, and `protocol()` members return the
+    three integers passed to the operating system's `socket()`
+    call. Their values are platform-defined constants taken from
+    the system socket headers. For an inline variant that includes
+    those headers, use @ref native_tcp.
 
     @par Example
     @code
@@ -72,10 +73,10 @@ class BOOST_COROSIO_DECL tcp
     /// Return the IP protocol (IPPROTO_TCP).
     static int protocol() noexcept;
 
-    /// The associated socket type.
+    /// The socket type to use with this protocol, @ref tcp_socket.
     using socket = tcp_socket;
 
-    /// The associated acceptor type.
+    /// The acceptor type to use with this protocol, @ref tcp_acceptor.
     using acceptor = tcp_acceptor;
 
     /// Test for equality.

include/boost/corosio/udp.hpp

@@ -22,10 +22,11 @@ class udp_socket;
     (IPv4 or IPv6). It is used to parameterize `udp_socket::open()`
     calls with a self-documenting type.
 
-    The `family()`, `type()`, and `protocol()` members are
-    implemented in the compiled library to avoid exposing
-    platform socket headers. For an inline variant that includes
-    platform headers, use @ref native_udp.
+    The `family()`, `type()`, and `protocol()` members return the
+    three integers passed to the operating system's `socket()`
+    call. Their values are platform-defined constants taken from
+    the system socket headers. For an inline variant that includes
+    those headers, use @ref native_udp.
 
     @par Example
     @code
@@ -69,7 +70,7 @@ class BOOST_COROSIO_DECL udp
     /// Return the IP protocol (IPPROTO_UDP).
     static int protocol() noexcept;
 
-    /// The associated socket type.
+    /// The socket type to use with this protocol, @ref udp_socket.
     using socket = udp_socket;
 
     /// Test for equality.