Doc fixes, adapted from suggestions by Martin Lambers <marlam@web.de>.

diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 07678e98edc37fcaa140cc6ff04ce7cd7d9e927a..57cbad64bfcf3ddaf74c6a5c738d22c498ad1a33 100644 (file)
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -983,18 +983,27 @@ ssize_t _gnutls_recv_int(gnutls_session_t session, content_type_t type,
   * difference is that is accepts a GNUTLS session, and uses different
   * error codes.
   *
+  * In the special case that a server requests a renegotiation, the
+  * client may receive an error code of %GNUTLS_E_REHANDSHAKE.  This
+  * message may be simply ignored, replied with an alert containing
+  * %GNUTLS_A_NO_RENEGOTIATION, or replied with a new handshake,
+  * depending on the client's will.
+  *
+  * A server may also receive %GNUTLS_E_REHANDSHAKE when a client has
+  * initiated a handshake. In that case the server can only initiate a
+  * handshake or terminate the connection.
+  *
   * If the EINTR is returned by the internal push function (the
-  * default is send()) then GNUTLS_E_INTERRUPTED will be returned. If
-  * GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call
-  * this function again, with the same parameters; alternatively you
-  * could provide a NULL pointer for data, and 0 for
+  * default is send()} then %GNUTLS_E_INTERRUPTED will be returned. If
+  * %GNUTLS_E_INTERRUPTED or %GNUTLS_E_AGAIN is returned, you must
+  * call this function again, with the same parameters; alternatively
+  * you could provide a %NULL pointer for data, and 0 for
   * size. cf. gnutls_record_get_direction().
   *
   * Returns the number of bytes sent, or a negative error code. The
   * number of bytes sent might be less than @sizeofdata. The maximum
   * number of bytes this function can send in a single call depends on
   * the negotiated maximum record size.
-  *
   **/
 ssize_t gnutls_record_send(gnutls_session_t session, const void *data,
                           size_t sizeofdata)
@@ -1006,26 +1015,33 @@ ssize_t gnutls_record_send(gnutls_session_t session, const void *data,
 /**
   * gnutls_record_recv - reads data from the TLS record protocol
   * @session: is a #gnutls_session_t structure.
-  * @data: contains the data to send
-  * @sizeofdata: is the length of the data
+  * @data: the buffer that the data will be read into
+  * @sizeofdata: the number of requested bytes
   *
   * This function has the similar semantics with recv(). The only
   * difference is that is accepts a GNUTLS session, and uses different
   * error codes.
   *
-  * In the special case that a server requests a renegotiation, the 
-  * client may receive an error code of GNUTLS_E_REHANDSHAKE. 
-  * This message may be simply ignored, replied with an alert 
-  * containing NO_RENEGOTIATION, or replied with a new handshake,
-  * depending on the client's will.
+  * In the special case that a server requests a renegotiation, the
+  * client may receive an error code of GNUTLS_E_REHANDSHAKE.  This
+  * message may be simply ignored, replied with an alert containing
+  * NO_RENEGOTIATION, or replied with a new handshake, depending on
+  * the client's will.
+  *
+  * If EINTR is returned by the internal push function (the default is
+  * @code{recv()}) then GNUTLS_E_INTERRUPTED will be returned. If
+  * GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call
+  * this function again, with the same parameters; alternatively you
+  * could provide a NULL pointer for data, and 0 for
+  * size. cf. @code{gnutls_record_get_direction()}.
   *
   * A server may also receive GNUTLS_E_REHANDSHAKE when a client has
   * initiated a handshake. In that case the server can only initiate a
   * handshake or terminate the connection.
   *
-  * Returns the number of bytes received and zero on EOF.
-  * A negative error code is returned in case of an error.
-  *
+  * Returns the number of bytes received and zero on EOF.  A negative
+  * error code is returned in case of an error.  The number of bytes
+  * received might be less than @code{count}.
   **/
 ssize_t gnutls_record_recv(gnutls_session_t session, void *data,
                           size_t sizeofdata)