doc: net: Minor fixes to BSD socket documentation

Some clarifications to BSD socket descriptions. Also added
rendering hints for some strings.

Signed-off-by: Jukka Rissanen <[email protected]>

Author: jukkar

doc/reference/networking/sockets.rst

@@ -17,15 +17,13 @@ and port existing simple networking applications to Zephyr.
 Here are the key requirements and concepts which governed BSD Sockets
 compatible API implementation for Zephyr:
 
-* Should have minimal overhead, similar to the requirement for other
+* Has minimal overhead, similar to the requirement for other
   Zephyr subsystems.
-* Should be implemented on top of
-  :ref:`native networking API <networking_api_usage>` to keep modular
-  design.
-* Should be namespaced by default, to avoid name conflicts with well-known
+* Is namespaced by default, to avoid name conflicts with well-known
   names like ``close()``, which may be part of libc or other POSIX
-  compatibility libraries. If enabled, should also expose native POSIX
-  names.
+  compatibility libraries.
+  If enabled by :option:`CONFIG_NET_SOCKETS_POSIX_NAMES`, it will also
+  expose native POSIX names.
 
 BSD Sockets compatible API is enabled using :option:`CONFIG_NET_SOCKETS`
 config option and implements the following operations: ``socket()``, ``close()``,
@@ -47,8 +45,8 @@ Another entailment of the design requirements above is that the Zephyr
 API aggressively employs the short-read/short-write property of the POSIX API
 whenever possible (to minimize complexity and overheads). POSIX allows
 for calls like ``recv()`` and ``send()`` to actually process (receive
-or send) less data than requested by the user (on SOCK_STREAM type sockets).
-For example, a call ``recv(sock, 1000, 0)`` may return 100,
+or send) less data than requested by the user (on ``SOCK_STREAM`` type
+sockets). For example, a call ``recv(sock, 1000, 0)`` may return 100,
 meaning that only 100 bytes were read (short read), and the application
 needs to retry call(s) to receive the remaining 900 bytes.
 
@@ -68,12 +66,12 @@ Zephyr provides an extension of standard POSIX socket API, allowing to create
 and configure sockets with TLS protocol types, facilitating secure
 communication. Secure functions for the implementation are provided by
 mbedTLS library. Secure sockets implementation allows use of both TLS and DTLS
-protocols with standard socket calls. See :c:type:`net_ip_protocol_secure` for
-supported secure protocol versions.
+protocols with standard socket calls. See :c:type:`net_ip_protocol_secure` type
+for supported secure protocol versions.
 
-To enable secure sockets, set the
-:option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS`
-option. To enable DTLS support, use :option:`CONFIG_NET_SOCKETS_ENABLE_DTLS`.
+To enable secure sockets, set the :option:`CONFIG_NET_SOCKETS_SOCKOPT_TLS`
+option. To enable DTLS support, use :option:`CONFIG_NET_SOCKETS_ENABLE_DTLS`
+option.
 
 TLS credentials subsystem
 =========================
@@ -120,7 +118,7 @@ CA certificate and hostname can be set:
 .. code-block:: c
 
    sec_tag_t sec_tag_opt[] = {
-      CA_CERTIFICATE_TAG,
+           CA_CERTIFICATE_TAG,
    };
 
    ret = setsockopt(sock, SOL_TLS, TLS_SEC_TAG_LIST,
@@ -130,12 +128,13 @@ CA certificate and hostname can be set:
 
    char host[] = "google.com";
 
-   ret = setsockopt(sock, SOL_TLS, TLS_HOSTNAME, host, sizeof(host));
+   ret = setsockopt(sock, SOL_TLS, TLS_HOSTNAME, host, sizeof(host) - 1);
 
 Once configured, socket can be used just like a regular TCP socket.
 
 Several samples in Zephyr use secure sockets for communication. For a sample use
-see e.g. :ref:`sockets-echo-server-sample` or :ref:`sockets-http-get`.
+see e.g. :ref:`echo-server sample application <sockets-echo-server-sample>` or
+:ref:`HTTP GET sample application <sockets-http-get>`.
 
 Secure Sockets options
 ======================