fixes #1914 Document nng_socket_proto_id, proto_name, peer_id, peer_n…

…ame, and nng_socket_raw

docs/ref/SUMMARY.md

@@ -8,6 +8,8 @@
 
   - [Messages](./api/msg.md)
 
+  - [Sockets](./api/sock.md)
+
   - [Memory](./api/memory.md)
 
   - [Time](./api/time.md)

docs/ref/api/sock.md

@@ -0,0 +1,60 @@
+# Sockets
+
+Sockets {{hi:socket}} in Scalability Protocols provide the handle for communication
+between peers. Sockets also encapsulate protocol specific semantics, such as
+filtering subscriptions, or automatically retrying requests.
+
+## Socket Structure
+
+```c
+#define NNG_SOCKET_INITIALIZER // opaque value
+
+typedef struct nng_socket_s nng_socket;
+```
+
+The {{i:`nng_socket`}} structure represents socket. This is a handle, and
+the members of it are opaque. However, unlike a pointer, it is usually
+passed by value.
+
+A socket may be initialized statically with the `NNG_SOCKET_INITIALIZER` macro,
+to ensure that it cannot be confused with a valid open socket.
+
+## Socket Identity
+
+```c
+int nng_socket_id(nng_socket s);
+int nng_socket_raw(nng_socket s, bool *raw);
+int nng_socket_proto_id(nng_socket s, uint16_t *proto);
+int nng_socket_peer_id(nng_socket s, uint16_t *proto);
+int nng_socket_proto_name(nng_socket s, const char **name);
+int nng_socket_peer_name(nng_socket s, const char **name);
+```
+
+These functions are used to provide fundamental information about the socket _s_.
+Most applications will not need to use these functions.
+
+The {{i:`nng_socket_id`}} function returns the numeric id, which will be a non-negative
+value, associated with the socket. If the socket is uninitialized (has never been opened),
+then the return value may be `-1`.
+
+The {{i:`nng_socket_proto_id`}} and {{i:`nng_socket_peer_id`}} functions provide the 16-bit
+protocol identifier for the socket's protocol, and of the protocol peers will use when
+communicating with the socket.
+
+The {{i:`nng_socket_proto_name`}} and {{i:`nng_socket_peer_name`}} functions provide the ASCII
+names of the socket's protocol, and of the protocol peers of the socket use.
+The value stored in _name_ is a fixed string located in program text, and must not be freed
+or altered. It is guaranteed to remain valid while this library is present.
+
+The {{i:`nng_socket_raw`}} function determines whether the socket is in
+[raw mode][raw] or not, storing `true` in _raw_ if it is, or `false` if it is not.
+
+## Examples
+
+### Example 1: Initializing a Socket
+
+```c
+nng_socket s = NNG_SOCKET_INITIALIZER;
+```
+
+{{#include ../xref.md}}

docs/ref/xref.md

@@ -66,6 +66,12 @@
 [`nng_aio_result`]: /api/aio.md#result-of-operation
 [`nng_aio_count`]: /api/aio.md#result-of-operation
 [`nng_aio_set_timeout`]: /api/aio.md#set-timeout
+[`nng_socket_id`]: /api/sock.md#socket-identity
+[`nng_socket_raw`]: /api/sock.md#socket-identity
+[`nng_socket_proto_id`]: /api/sock.md#socket-identity
+[`nng_socket_proto_name`]: /api/sock.md#socket-identity
+[`nng_socket_peer_id`]: /api/sock.md#socket-identity
+[`nng_socket_peer_name`]: /api/sock.md#socket-identity
 [`nng_opts_parse`]: /api/cmd_opts.md#parse-command-line-options
 [`nng_aio_begin`]: /TODO.md
 [`nng_aio_defer`]: /TODO.md