Doc fix.

1 files changed, 59 insertions, 61 deletions

diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 4648618746..576917c409 100644
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -48,8 +48,7 @@
   * gnutls_protocol_get_version - Returns the version of the currently used protocol
   * @session: is a #gnutls_session_t structure.
   *
-  * Returns the version of the currently used protocol. 
-  *
+  * Returns: the version of the currently used protocol.
   **/
 gnutls_protocol_t
 gnutls_protocol_get_version (gnutls_session_t session)
@@ -69,13 +68,12 @@ _gnutls_set_current_version (gnutls_session_t session,
   * @session: is a #gnutls_session_t structure.
   * @num: is the low water value.
   *
-  * Used to set the lowat value in order for select to check
-  * if there are pending data to socket buffer. Used only   
-  * if you have changed the default low water value (default is 1).
-  * Normally you will not need that function. 
-  * This function is only useful if using berkeley style sockets.
-  * Otherwise it must be called and set lowat to zero.
-  *
+  * Used to set the lowat value in order for select to check if there
+  * are pending data to socket buffer. Used only if you have changed
+  * the default low water value (default is 1).  Normally you will not
+  * need that function.  This function is only useful if using
+  * berkeley style sockets.  Otherwise it must be called and set lowat
+  * to zero.
   **/
 void
 gnutls_transport_set_lowat (gnutls_session_t session, int num)
@@ -87,14 +85,13 @@ gnutls_transport_set_lowat (gnutls_session_t session, int num)
   * gnutls_record_disable_padding - Used to disabled padding in TLS 1.0 and above
   * @session: is a #gnutls_session_t structure.
   *
-  * Used to disabled padding in TLS 1.0 and above. Normally you do not need
-  * to use this function, but there are buggy clients that complain if a
-  * server pads the encrypted data. This of course will disable protection
-  * against statistical attacks on the data.
+  * Used to disabled padding in TLS 1.0 and above.  Normally you do
+  * not need to use this function, but there are buggy clients that
+  * complain if a server pads the encrypted data.  This of course will
+  * disable protection against statistical attacks on the data.
   *
   * Normally only servers that require maximum compatibility with everything
   * out there, need to call this function.
-  *
   **/
 void
 gnutls_record_disable_padding (gnutls_session_t session)
@@ -107,10 +104,9 @@ gnutls_record_disable_padding (gnutls_session_t session)
   * @session: is a #gnutls_session_t structure.
   * @ptr: is the value.
   *
-  * Used to set the first argument of the transport function (like PUSH and
-  * PULL). In berkeley style sockets this function will set the connection
-  * handle.
-  *
+  * Used to set the first argument of the transport function (like
+  * PUSH and PULL).  In berkeley style sockets this function will set
+  * the connection handle.
   **/
 void
 gnutls_transport_set_ptr (gnutls_session_t session,
@@ -127,11 +123,10 @@ gnutls_transport_set_ptr (gnutls_session_t session,
   * @recv_ptr: is the value for the pull function
   * @send_ptr: is the value for the push function
   *
-  * Used to set the first argument of the transport function (like PUSH and
-  * PULL). In berkeley style sockets this function will set the connection
-  * handle. With this function you can use two different pointers for
-  * receiving and sending.
-  *
+  * Used to set the first argument of the transport function (like
+  * PUSH and PULL). In berkeley style sockets this function will set
+  * the connection handle.  With this function you can use two
+  * different pointers for receiving and sending.
   **/
 void
 gnutls_transport_set_ptr2 (gnutls_session_t session,
@@ -146,9 +141,11 @@ gnutls_transport_set_ptr2 (gnutls_session_t session,
   * gnutls_transport_get_ptr - Used to return the first argument of the transport functions
   * @session: is a #gnutls_session_t structure.
   *
-  * Used to get the first argument of the transport function (like PUSH and
-  * PULL). This must have been set using gnutls_transport_set_ptr().
+  * Used to get the first argument of the transport function (like
+  * PUSH and PULL).  This must have been set using
+  * gnutls_transport_set_ptr().
   *
+  * Returns: first argument of the transport function.
   **/
 gnutls_transport_ptr_t
 gnutls_transport_get_ptr (gnutls_session_t session)
@@ -162,9 +159,9 @@ gnutls_transport_get_ptr (gnutls_session_t session)
   * @recv_ptr: will hold the value for the pull function
   * @send_ptr: will hold the value for the push function
   *
-  * Used to get the arguments of the transport functions (like PUSH and
-  * PULL). These should have been set using gnutls_transport_set_ptr2().
-  *
+  * Used to get the arguments of the transport functions (like PUSH
+  * and PULL).  These should have been set using
+  * gnutls_transport_set_ptr2().
   **/
 void
 gnutls_transport_get_ptr2 (gnutls_session_t session,
@@ -182,29 +179,32 @@ gnutls_transport_get_ptr2 (gnutls_session_t session,
   * @how: is an integer
   *
   * Terminates the current TLS/SSL connection. The connection should
-  * have been initiated using gnutls_handshake().
-  * @how should be one of GNUTLS_SHUT_RDWR, GNUTLS_SHUT_WR.
+  * have been initiated using gnutls_handshake().  @how should be one
+  * of %GNUTLS_SHUT_RDWR, %GNUTLS_SHUT_WR.
   *
-  * In case of GNUTLS_SHUT_RDWR then the TLS connection gets terminated and
-  * further receives and sends will be disallowed. If the return
-  * value is zero you may continue using the connection.
-  * GNUTLS_SHUT_RDWR actually sends an alert containing a close request
-  * and waits for the peer to reply with the same message.
+  * In case of %GNUTLS_SHUT_RDWR then the TLS connection gets
+  * terminated and further receives and sends will be disallowed.  If
+  * the return value is zero you may continue using the connection.
+  * %GNUTLS_SHUT_RDWR actually sends an alert containing a close
+  * request and waits for the peer to reply with the same message.
   *
-  * In case of GNUTLS_SHUT_WR then the TLS connection gets terminated and
-  * further sends will be disallowed. In order to reuse the connection
-  * you should wait for an EOF from the peer.
-  * GNUTLS_SHUT_WR sends an alert containing a close request.
+  * In case of %GNUTLS_SHUT_WR then the TLS connection gets terminated
+  * and further sends will be disallowed. In order to reuse the
+  * connection you should wait for an EOF from the peer.
+  * %GNUTLS_SHUT_WR sends an alert containing a close request.
   *
-  * Note that not all implementations will properly terminate a TLS connection.
-  * Some of them, usually for performance reasons, will terminate only the 
-  * underlying transport layer, thus causing a transmission error to the peer.
-  * This error cannot be distinguished from a malicious party prematurely terminating
-  * the session, thus this behavior is not recommended.
+  * Note that not all implementations will properly terminate a TLS
+  * connection.  Some of them, usually for performance reasons, will
+  * terminate only the underlying transport layer, thus causing a
+  * transmission error to the peer.  This error cannot be
+  * distinguished from a malicious party prematurely terminating the
+  * session, thus this behavior is not recommended.
   *
-  * This function may also return GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED; cf.
-  * gnutls_record_get_direction().
+  * This function may also return %GNUTLS_E_AGAIN or
+  * %GNUTLS_E_INTERRUPTED; cf.  gnutls_record_get_direction().
   *
+  * Returns: %GNUTLS_E_SUCCESS on success, or an error code, see
+  *   function documentation for entire semantics.
   **/
 int
 gnutls_bye (gnutls_session_t session, gnutls_close_request_t how)
@@ -1119,8 +1119,8 @@ begin:
   * 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
+  * 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.
   **/
@@ -1158,7 +1158,7 @@ gnutls_record_send (gnutls_session_t session, const void *data,
   * 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
+  * 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 @sizeofdata.
   **/
@@ -1173,10 +1173,9 @@ gnutls_record_recv (gnutls_session_t session, void *data, size_t sizeofdata)
   * gnutls_record_get_max_size - returns the maximum record size
   * @session: is a #gnutls_session_t structure.
   *
-  * This function returns the maximum record packet size in this connection.
-  * The maximum record size is negotiated by the client after the
-  * first handshake message.
-  *
+  * This function returns the maximum record packet size in this
+  * connection.  The maximum record size is negotiated by the client
+  * after the first handshake message.
   **/
 size_t
 gnutls_record_get_max_size (gnutls_session_t session)
@@ -1193,18 +1192,17 @@ gnutls_record_get_max_size (gnutls_session_t session)
   * @session: is a #gnutls_session_t structure.
   * @size: is the new size
   *
-  * This function sets the maximum record packet size in this connection.
-  * This property can only be set to clients. The server may
-  * choose not to accept the requested size.
+  * This function sets the maximum record packet size in this
+  * connection.  This property can only be set to clients.  The server
+  * may choose not to accept the requested size.
   *
-  * Acceptable values are 512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12).
-  * Returns 0 on success. The requested record size does
+  * Acceptable values are 512(=2^9), 1024(=2^10), 2048(=2^11) and
+  * 4096(=2^12).  Returns 0 on success. The requested record size does
   * get in effect immediately only while sending data. The receive
   * part will take effect after a successful handshake.
   *
-  * This function uses a TLS extension called 'max record size'.
-  * Not all TLS implementations use or even understand this extension.
-  *
+  * This function uses a TLS extension called 'max record size'.  Not
+  * all TLS implementations use or even understand this extension.
   **/
 ssize_t
 gnutls_record_set_max_size (gnutls_session_t session, size_t size)