diff --git a/src/ssl/connection.c b/src/ssl/connection.c
index f78e93f..2d309cd 100755
--- a/src/ssl/connection.c
+++ b/src/ssl/connection.c
@@ -250,9 +250,7 @@
 static char ssl_Connection_get_context_doc[] = "\n\
 Get session context\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A Context object\n\
+@return: A Context object\n\
 ";
 static PyObject *
 ssl_Connection_get_context(ssl_ConnectionObj *self, PyObject *args)
@@ -267,9 +265,7 @@
 static char ssl_Connection_pending_doc[] = "\n\
 Get the number of bytes that can be safely read from the connection\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   \n\
+@return: The number of bytes available in the receive buffer.\n\
 ";
 static PyObject *
 ssl_Connection_pending(ssl_ConnectionObj *self, PyObject *args)
@@ -287,10 +283,8 @@
 When using non-socket connections this function sends\n\
 \"dirty\" data that would have traveled in on the network.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             buf   - The string to bio_write\n\
-Returns:   The number of bytes written\n\
+@param buf: The string to put into the memory BIO.\n\
+@return: The number of bytes written\n\
 ";
 static PyObject *
 ssl_Connection_bio_write(ssl_ConnectionObj *self, PyObject *args)
@@ -331,12 +325,10 @@
 WantWrite or WantX509Lookup exceptions on this, you have to call the\n\
 method again with the SAME buffer.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             buf   - The string to send\n\
-             flags - (optional) Included for compatability with the socket\n\
-                     API, the value is ignored\n\
-Returns:   The number of bytes written\n\
+@param buf: The string to send\n\
+@param flags: (optional) Included for compatability with the socket\n\
+              API, the value is ignored\n\
+@return: The number of bytes written\n\
 ";
 static PyObject *
 ssl_Connection_send(ssl_ConnectionObj *self, PyObject *args)
@@ -374,12 +366,10 @@
 all data is sent. If an error occurs, it's impossible to tell how much data\n\
 has been sent.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             buf   - The string to send\n\
-             flags - (optional) Included for compatability with the socket\n\
-                     API, the value is ignored\n\
-Returns:   The number of bytes written\n\
+@param buf: The string to send\n\
+@param flags: (optional) Included for compatability with the socket\n\
+              API, the value is ignored\n\
+@return: The number of bytes written\n\
 ";
 static PyObject *
 ssl_Connection_sendall(ssl_ConnectionObj *self, PyObject *args)
@@ -425,12 +415,10 @@
 WantWrite or WantX509Lookup exceptions on this, you have to call the\n\
 method again with the SAME buffer.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             bufsiz - The maximum number of bytes to read\n\
-             flags  - (optional) Included for compatability with the socket\n\
-                      API, the value is ignored\n\
-Returns:   The number of bytes read\n\
+@param bufsiz: The maximum number of bytes to read\n\
+@param flags: (optional) Included for compatability with the socket\n\
+              API, the value is ignored\n\
+@return: The string read from the Connection\n\
 ";
 static PyObject *
 ssl_Connection_recv(ssl_ConnectionObj *self, PyObject *args)
@@ -475,10 +463,8 @@
 When using non-socket connections this function reads\n\
 the \"dirty\" data that would have traveled away on the network.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             bufsiz - The maximum number of bytes to read\n\
-Returns:   The string read.\n\
+@param bufsiz: The maximum number of bytes to read\n\
+@return: The string read.\n\
 ";
 static PyObject *
 ssl_Connection_bio_read(ssl_ConnectionObj *self, PyObject *args)
@@ -531,9 +517,7 @@
 static char ssl_Connection_renegotiate_doc[] = "\n\
 Renegotiate the session\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True if the renegotiation can be started, false otherwise\n\
+@return: True if the renegotiation can be started, false otherwise\n\
 ";
 static PyObject *
 ssl_Connection_renegotiate(ssl_ConnectionObj *self, PyObject *args)
@@ -560,9 +544,7 @@
 Perform an SSL handshake (usually called after renegotiate() or one of\n\
 set_*_state()). This can raise the same exceptions as send and recv.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None.\n\
+@return: None.\n\
 ";
 static PyObject *
 ssl_Connection_do_handshake(ssl_ConnectionObj *self, PyObject *args)
@@ -600,9 +582,7 @@
 Check if there's a renegotiation in progress, it will return false once\n\
 a renegotiation is finished.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   Whether there's a renegotiation in progress\n\
+@return: Whether there's a renegotiation in progress\n\
 ";
 static PyObject *
 ssl_Connection_renegotiate_pending(ssl_ConnectionObj *self, PyObject *args)
@@ -617,9 +597,7 @@
 static char ssl_Connection_total_renegotiations_doc[] = "\n\
 Find out the total number of renegotiations.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The number of renegotiations.\n\
+@return: The number of renegotiations.\n\
 ";
 static PyObject *
 ssl_Connection_total_renegotiations(ssl_ConnectionObj *self, PyObject *args)
@@ -634,9 +612,7 @@
 Set the connection to work in server mode. The handshake will be handled\n\
 automatically by read/write.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Connection_set_accept_state(ssl_ConnectionObj *self, PyObject *args)
@@ -654,9 +630,7 @@
 Set the connection to work in client mode. The handshake will be handled\n\
 automatically by read/write.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Connection_set_connect_state(ssl_ConnectionObj *self, PyObject *args)
@@ -673,10 +647,8 @@
 static char ssl_Connection_connect_doc[] = "\n\
 Connect to remote host and set up client-side SSL\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             addr - A remote address\n\
-Returns:   What the socket's connect method returns\n\
+@param addr: A remote address\n\
+@return: What the socket's connect method returns\n\
 ";
 static PyObject *
 ssl_Connection_connect(ssl_ConnectionObj *self, PyObject *args)
@@ -700,10 +672,8 @@
 Connect to remote host and set up client-side SSL. Note that if the socket's\n\
 connect_ex method doesn't return 0, SSL won't be initialized.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be:\n\
-             addr - A remove address\n\
-Returns:   What the socket's connect_ex method returns\n\
+@param addr: A remove address\n\
+@return: What the socket's connect_ex method returns\n\
 ";
 static PyObject *
 ssl_Connection_connect_ex(ssl_ConnectionObj *self, PyObject *args)
@@ -728,10 +698,8 @@
 static char ssl_Connection_accept_doc[] = "\n\
 Accept incoming connection and set up SSL on it\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A (conn,addr) pair where conn is a Connection and addr is an\n\
-           address\n\
+@return: A (conn,addr) pair where conn is a Connection and addr is an\n\
+         address\n\
 ";
 static PyObject *
 ssl_Connection_accept(ssl_ConnectionObj *self, PyObject *args)
@@ -774,9 +742,7 @@
 When using non-socket connections this function signals end of\n\
 data on the input for this connection.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty.\n\
-Returns:   Nothing\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -798,11 +764,9 @@
 static char ssl_Connection_shutdown_doc[] = "\n\
 Send closure alert\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True if the shutdown completed successfully (i.e. both sides\n\
-           have sent closure alerts), false otherwise (i.e. you have to\n\
-           wait for a ZeroReturnError on a recv() method call\n\
+@return: True if the shutdown completed successfully (i.e. both sides\n\
+         have sent closure alerts), false otherwise (i.e. you have to\n\
+         wait for a ZeroReturnError on a recv() method call\n\
 ";
 static PyObject *
 ssl_Connection_shutdown(ssl_ConnectionObj *self, PyObject *args)
@@ -841,12 +805,8 @@
 
 static char ssl_Connection_get_cipher_list_doc[] = "\n\
 Get the session cipher list\n\
-WARNING: API change! This used to take an optional argument, and return a\n\
-string.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A list of cipher strings\n\
+@return: A list of cipher strings\n\
 ";
 static PyObject *
 ssl_Connection_get_cipher_list(ssl_ConnectionObj *self, PyObject *args)
@@ -872,11 +832,8 @@
 static char ssl_Connection_makefile_doc[] = "\n\
 The makefile() method is not implemented, since there is no dup semantics\n\
 for SSL connections\n\
-XXX: Return self instead?\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   NULL\n\
+@raise NotImplementedError\n\
 ";
 static PyObject *
 ssl_Connection_makefile(ssl_ConnectionObj *self, PyObject *args)
@@ -888,9 +845,7 @@
 static char ssl_Connection_get_app_data_doc[] = "\n\
 Get application data\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The application data\n\
+@return: The application data\n\
 ";
 static PyObject *
 ssl_Connection_get_app_data(ssl_ConnectionObj *self, PyObject *args)
@@ -905,10 +860,8 @@
 static char ssl_Connection_set_app_data_doc[] = "\n\
 Set application data\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be\n\
-             data - The application data\n\
-Returns:   None\n\
+@param data - The application data\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Connection_set_app_data(ssl_ConnectionObj *self, PyObject *args)
@@ -929,9 +882,7 @@
 static char ssl_Connection_get_shutdown_doc[] = "\n\
 Get shutdown state\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The shutdown state, a bitmask of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.\n\
+@return: The shutdown state, a bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.\n\
 ";
 static PyObject *
 ssl_Connection_get_shutdown(ssl_ConnectionObj *self, PyObject *args)
@@ -945,10 +896,8 @@
 static char ssl_Connection_set_shutdown_doc[] = "\n\
 Set shutdown state\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be\n\
-             shutdown state - bitmask of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.\n\
-Returns:   None\n\
+@param state - bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Connection_set_shutdown(ssl_ConnectionObj *self, PyObject *args)
@@ -966,9 +915,7 @@
 static char ssl_Connection_state_string_doc[] = "\n\
 Get a verbose state description\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A string representing the state\n\
+@return: A string representing the state\n\
 ";
 static PyObject *
 ssl_Connection_state_string(ssl_ConnectionObj *self, PyObject *args)
@@ -982,9 +929,7 @@
 static char ssl_Connection_client_random_doc[] = "\n\
 Get a copy of the client hello nonce.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A string representing the state\n\
+@return: A string representing the state\n\
 ";
 static PyObject *
 ssl_Connection_client_random(ssl_ConnectionObj *self, PyObject *args)
@@ -1002,9 +947,7 @@
 static char ssl_Connection_server_random_doc[] = "\n\
 Get a copy of the server hello nonce.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A string representing the state\n\
+@return: A string representing the state\n\
 ";
 static PyObject *
 ssl_Connection_server_random(ssl_ConnectionObj *self, PyObject *args)
@@ -1022,9 +965,7 @@
 static char ssl_Connection_master_key_doc[] = "\n\
 Get a copy of the master key.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A string representing the state\n\
+@return: A string representing the state\n\
 ";
 static PyObject *
 ssl_Connection_master_key(ssl_ConnectionObj *self, PyObject *args)
@@ -1042,10 +983,7 @@
 static char ssl_Connection_sock_shutdown_doc[] = "\n\
 See shutdown(2)\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be whatever the\n\
-                  socket's shutdown() method expects\n\
-Returns:   What the socket's shutdown() method returns\n\
+@return: What the socket's shutdown() method returns\n\
 ";
 static PyObject *
 ssl_Connection_sock_shutdown(ssl_ConnectionObj *self, PyObject *args)
@@ -1062,9 +1000,7 @@
 static char ssl_Connection_get_peer_certificate_doc[] = "\n\
 Retrieve the other side's certificate (if any)\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The peer's certificate\n\
+@return: The peer's certificate\n\
 ";
 static PyObject *
 ssl_Connection_get_peer_certificate(ssl_ConnectionObj *self, PyObject *args)
@@ -1090,9 +1026,7 @@
 Checks if more data has to be read from the transport layer to complete an\n\
 operation.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True iff more data has to be read\n\
+@return: True iff more data has to be read\n\
 ";
 static PyObject *
 ssl_Connection_want_read(ssl_ConnectionObj *self, PyObject *args)
@@ -1107,9 +1041,7 @@
 Checks if there is data to write to the transport layer to complete an\n\
 operation.\n\
 \n\
-Arguments: self - The Connection object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True iff there is data to write\n\
+@return: True iff there is data to write\n\
 ";
 static PyObject *
 ssl_Connection_want_write(ssl_ConnectionObj *self, PyObject *args)
diff --git a/src/ssl/context.c b/src/ssl/context.c
index 1fecc9b..c1e1934 100644
--- a/src/ssl/context.c
+++ b/src/ssl/context.c
@@ -242,11 +242,9 @@
 Let SSL know where we can find trusted certificates for the certificate\n\
 chain\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             cafile - In which file we can find the certificates\n\
-             capath - In which directory we can find the certificates\r\
-Returns:   None\n\
+@param cafile: In which file we can find the certificates\n\
+@param capath: In which directory we can find the certificates\r\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_load_verify_locations(ssl_ContextObj *self, PyObject *args) {
@@ -272,10 +270,7 @@
 static char ssl_Context_set_default_verify_paths_doc[] = "\n\
 Use the platform-specific CA certificate locations\n\
 \n\
-Arguments: self - The Context object\n\
-           args - None\n\
-\n\
-Returns:   None\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_default_verify_paths(ssl_ContextObj *self, PyObject *args) {
@@ -299,12 +294,10 @@
 static char ssl_Context_set_passwd_cb_doc[] = "\n\
 Set the passphrase callback\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             callback - The Python callback to use\n\
-             userdata - (optional) A Python object which will be given as\n\
-                        argument to the callback\n\
-Returns:   None\n\
+@param callback: The Python callback to use\n\
+@param userdata: (optional) A Python object which will be given as\n\
+                 argument to the callback\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_passwd_cb(ssl_ContextObj *self, PyObject *args)
@@ -371,10 +364,8 @@
 static char ssl_Context_add_extra_chain_cert_doc[] = "\n\
 Add certificate to chain\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             certobj - The X509 certificate object to add to the chain\n\
-Returns:   None\n\
+@param certobj: The X509 certificate object to add to the chain\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -410,10 +401,8 @@
 static char ssl_Context_use_certificate_chain_file_doc[] = "\n\
 Load a certificate chain from a file\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             certfile - The name of the certificate chain file\n\
-Returns:   None\n\
+@param certfile: The name of the certificate chain file\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_use_certificate_chain_file(ssl_ContextObj *self, PyObject *args)
@@ -439,11 +428,9 @@
 static char ssl_Context_use_certificate_file_doc[] = "\n\
 Load a certificate from a file\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             certfile - The name of the certificate file\n\
-             filetype - (optional) The encoding of the file, default is PEM\n\
-Returns:   None\n\
+@param certfile: The name of the certificate file\n\
+@param filetype: (optional) The encoding of the file, default is PEM\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_use_certificate_file(ssl_ContextObj *self, PyObject *args)
@@ -469,10 +456,8 @@
 static char ssl_Context_use_certificate_doc[] = "\n\
 Load a certificate from a X509 object\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             cert - The X509 object\n\
-Returns:   None\n\
+@param cert: The X509 object\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_use_certificate(ssl_ContextObj *self, PyObject *args)
@@ -498,11 +483,9 @@
 static char ssl_Context_use_privatekey_file_doc[] = "\n\
 Load a private key from a file\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             keyfile  - The name of the key file\n\
-             filetype - (optional) The encoding of the file, default is PEM\n\
-Returns:   None\n\
+@param keyfile: The name of the key file\n\
+@param filetype: (optional) The encoding of the file, default is PEM\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_use_privatekey_file(ssl_ContextObj *self, PyObject *args)
@@ -538,10 +521,8 @@
 static char ssl_Context_use_privatekey_doc[] = "\n\
 Load a private key from a PKey object\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey - The PKey object\n\
-Returns:   None\n\
+@param pkey: The PKey object\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_use_privatekey(ssl_ContextObj *self, PyObject *args)
@@ -589,9 +570,7 @@
 static char ssl_Context_check_privatekey_doc[] = "\n\
 Check that the private key and certificate match up\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None (raises an exception if something's wrong)\n\
+@return: None (raises an exception if something's wrong)\n\
 ";
 static PyObject *
 ssl_Context_check_privatekey(ssl_ContextObj *self, PyObject *args)
@@ -615,10 +594,8 @@
 Load the trusted certificates that will be sent to the client (basically\n\
 telling the client \"These are the guys I trust\")\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             cafile - The name of the certificates file\n\
-Returns:   None\n\
+@param cafile: The name of the certificates file\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_load_client_ca(ssl_ContextObj *self, PyObject *args)
@@ -638,10 +615,8 @@
 Set the session identifier, this is needed if you want to do session\n\
 resumption (which, ironically, isn't implemented yet)\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             buf - A Python object that can be safely converted to a string\n\
-Returns:   None\n\
+@param buf: A Python object that can be safely converted to a string\n\
+@returns: None\n\
 ";
 static PyObject *
 ssl_Context_set_session_id(ssl_ContextObj *self, PyObject *args)
@@ -667,12 +642,10 @@
 static char ssl_Context_set_verify_doc[] = "\n\
 Set the verify mode and verify callback\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             mode     - The verify mode, this is either VERIFY_NONE or\n\
-                        VERIFY_PEER combined with possible other flags\n\
-             callback - The Python callback to use\n\
-Returns:   None\n\
+@param mode: The verify mode, this is either VERIFY_NONE or\n\
+             VERIFY_PEER combined with possible other flags\n\
+@param callback: The Python callback to use\n\
+@return: None\n\
 \n\
 See SSL_CTX_set_verify(3SSL) for further details.\n\
 ";
@@ -703,10 +676,8 @@
 static char ssl_Context_set_verify_depth_doc[] = "\n\
 Set the verify depth\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             depth - An integer specifying the verify depth\n\
-Returns:   None\n\
+@param depth: An integer specifying the verify depth\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_verify_depth(ssl_ContextObj *self, PyObject *args)
@@ -724,9 +695,7 @@
 static char ssl_Context_get_verify_mode_doc[] = "\n\
 Get the verify mode\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The verify mode\n\
+@return: The verify mode\n\
 ";
 static PyObject *
 ssl_Context_get_verify_mode(ssl_ContextObj *self, PyObject *args)
@@ -743,9 +712,7 @@
 static char ssl_Context_get_verify_depth_doc[] = "\n\
 Get the verify depth\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The verify depth\n\
+@return: The verify depth\n\
 ";
 static PyObject *
 ssl_Context_get_verify_depth(ssl_ContextObj *self, PyObject *args)
@@ -762,10 +729,8 @@
 static char ssl_Context_load_tmp_dh_doc[] = "\n\
 Load parameters for Ephemeral Diffie-Hellman\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             dhfile - The file to load EDH parameters from\n\
-Returns:   None\n\
+@param dhfile: The file to load EDH parameters from\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_load_tmp_dh(ssl_ContextObj *self, PyObject *args)
@@ -793,10 +758,8 @@
 static char ssl_Context_set_cipher_list_doc[] = "\n\
 Change the cipher list\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             cipher_list - A cipher list, see ciphers(1)\n\
-Returns:   None\n\
+@param cipher_list: A cipher list, see ciphers(1)\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_cipher_list(ssl_ContextObj *self, PyObject *args)
@@ -821,10 +784,8 @@
 static char ssl_Context_set_timeout_doc[] = "\n\
 Set session timeout\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             t - The timeout in seconds\n\
-Returns:   The previous session timeout\n\
+@param timeout: The timeout in seconds\n\
+@return: The previous session timeout\n\
 ";
 static PyObject *
 ssl_Context_set_timeout(ssl_ContextObj *self, PyObject *args)
@@ -841,9 +802,7 @@
 static char ssl_Context_get_timeout_doc[] = "\n\
 Get the session timeout\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The session timeout\n\
+@return: The session timeout\n\
 ";
 static PyObject *
 ssl_Context_get_timeout(ssl_ContextObj *self, PyObject *args)
@@ -860,10 +819,8 @@
 static char ssl_Context_set_info_callback_doc[] = "\n\
 Set the info callback\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             callback - The Python callback to use\n\
-Returns:   None\n\
+@param callback: The Python callback to use\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_info_callback(ssl_ContextObj *self, PyObject *args)
@@ -891,9 +848,7 @@
 static char ssl_Context_get_app_data_doc[] = "\n\
 Get the application data (supplied via set_app_data())\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The application data\n\
+@return: The application data\n\
 ";
 static PyObject *
 ssl_Context_get_app_data(ssl_ContextObj *self, PyObject *args)
@@ -908,10 +863,8 @@
 static char ssl_Context_set_app_data_doc[] = "\n\
 Set the application data (will be returned from get_app_data())\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             data - Any Python object\n\
-Returns:   None\n\
+@param data: Any Python object\n\
+@return: None\n\
 ";
 static PyObject *
 ssl_Context_set_app_data(ssl_ContextObj *self, PyObject *args)
@@ -932,9 +885,7 @@
 static char ssl_Context_get_cert_store_doc[] = "\n\
 Get the certificate store for the context\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A X509Store object\n\
+@return: A X509Store object\n\
 ";
 static PyObject *
 ssl_Context_get_cert_store(ssl_ContextObj *self, PyObject *args)
@@ -958,10 +909,8 @@
 static char ssl_Context_set_options_doc[] = "\n\
 Add options. Options set before are not cleared!\n\
 \n\
-Arguments: self - The Context object\n\
-           args - The Python argument tuple, should be:\n\
-             options - The options to add.\n\
-Returns:   The new option bitmask.\n\
+@param options: The options to add.\n\
+@return: The new option bitmask.\n\
 ";
 static PyObject *
 ssl_Context_set_options(ssl_ContextObj *self, PyObject *args)
diff --git a/src/ssl/ssl.c b/src/ssl/ssl.c
index f1c51aa..2b8402d 100644
--- a/src/ssl/ssl.c
+++ b/src/ssl/ssl.c
@@ -46,10 +46,8 @@
 The factory function inserted in the module dictionary to create Context\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             method - The SSL method to use\n\
-Returns:   The Context object\n\
+@param method: The SSL method to use\n\
+@return: The Context object\n\
 ";
 
 static PyObject *
@@ -67,11 +65,9 @@
 The factory function inserted in the module dictionary to create Connection\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             ctx  - An SSL Context to use for this connection\n\
-             sock - The socket to use for transport layer\n\
-Returns:   The Connection object\n\
+@param ctx: An SSL Context to use for this connection\n\
+@param sock: The socket to use for transport layer\n\
+@return: The Connection object\n\
 ";
 
 static PyObject *