diff --git a/src/crypto/crypto.c b/src/crypto/crypto.c
index 257c016..e12c72a 100644
--- a/src/crypto/crypto.c
+++ b/src/crypto/crypto.c
@@ -49,14 +49,13 @@
 static char crypto_load_privatekey_doc[] = "\n\
 Load a private key from a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type       - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
-             buffer     - The buffer the key is stored in\n\
-             passphrase - (optional) if encrypted PEM format, this can be\n\
-                          either the passphrase to use, or a callback for\n\
-                          providing the passphrase.\n\
-Returns:   The PKey object\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param buffer: The buffer the key is stored in\n\
+@param passphrase: (optional) if encrypted PEM format, this can be\n\
+                   either the passphrase to use, or a callback for\n\
+                   providing the passphrase.\n\
+\n\
+@return: The PKey object\n\
 ";
 
 static PyObject *
@@ -123,16 +122,15 @@
 static char crypto_dump_privatekey_doc[] = "\n\
 Dump a private key to a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type       - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
-             pkey       - The PKey to dump\n\
-             cipher     - (optional) if encrypted PEM format, the cipher to\n\
-                          use\n\
-             passphrase - (optional) if encrypted PEM format, this can be either\n\
-                          the passphrase to use, or a callback for providing the\n\
-                          passphrase.\n\
-Returns:   The buffer with the dumped key in\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param pkey: The PKey to dump\n\
+@param cipher: (optional) if encrypted PEM format, the cipher to\n\
+               use\n\
+@param passphrase - (optional) if encrypted PEM format, this can be either\n\
+                    the passphrase to use, or a callback for providing the\n\
+                    passphrase.\n\
+@return: The buffer with the dumped key in\n\
+@rtype: C{str}\n\
 ";
 
 static PyObject *
@@ -229,11 +227,9 @@
 static char crypto_load_certificate_doc[] = "\n\
 Load a certificate from a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type   - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
              buffer - The buffer the certificate is stored in\n\
-Returns:   The X509 object\n\
+@return: The X509 object\n\
 ";
 
 static PyObject *
@@ -278,11 +274,9 @@
 static char crypto_dump_certificate_doc[] = "\n\
 Dump a certificate to a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
-             cert - The certificate to dump\n\
-Returns:   The buffer with the dumped certificate in\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param cert: The certificate to dump\n\
+@return: The buffer with the dumped certificate in\n\
 ";
 
 static PyObject *
@@ -336,11 +330,9 @@
 static char crypto_load_certificate_request_doc[] = "\n\
 Load a certificate request from a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type   - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
              buffer - The buffer the certificate request is stored in\n\
-Returns:   The X509Req object\n\
+@return: The X509Req object\n\
 ";
 
 static PyObject *
@@ -385,11 +377,9 @@
 static char crypto_dump_certificate_request_doc[] = "\n\
 Dump a certificate request to a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             type - The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
+@param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)\n\
              req  - The certificate request to dump\n\
-Returns:   The buffer with the dumped certificate request in\n\
+@return: The buffer with the dumped certificate request in\n\
 ";
 
 static PyObject *
@@ -443,11 +433,9 @@
 static char crypto_load_pkcs7_data_doc[] = "\n\
 Load pkcs7 data from a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The argument tuple, should be:\n\
-             type - The file type (one of FILETYPE_PEM or FILETYPE_ASN1)\n\
+@param type: The file type (one of FILETYPE_PEM or FILETYPE_ASN1)\n\
              buffer - The buffer with the pkcs7 data.\n\
-Returns: The PKCS7 object\n\
+@return: The PKCS7 object\n\
 ";
 
 static PyObject *
@@ -497,11 +485,9 @@
 static char crypto_load_pkcs12_doc[] = "\n\
 Load a PKCS12 object from a buffer\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             buffer - The buffer the certificate is stored in\n\
-             passphrase (Optional) - The password to decrypt the PKCS12 lump\n\
-Returns:   The PKCS12 object\n\
+@param buffer: The buffer the certificate is stored in\n\
+               passphrase (Optional) - The password to decrypt the PKCS12 lump\n\
+@returns: The PKCS12 object\n\
 ";
 
 static PyObject *
@@ -533,9 +519,7 @@
 The factory function inserted in the module dictionary to create X509\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The X509 object\n\
+@returns: The X509 object\n\
 ";
 
 static PyObject *
@@ -551,10 +535,8 @@
 The factory function inserted in the module dictionary as a copy\n\
 constructor for X509Name objects.\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             name - An X509Name object to copy\n\
-Returns:   The X509Name object\n\
+@param name: An X509Name object to copy\n\
+@return: The X509Name object\n\
 ";
 
 static PyObject *
@@ -572,9 +554,7 @@
 The factory function inserted in the module dictionary to create X509Req\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The X509Req object\n\
+@returns: The X509Req object\n\
 ";
 
 static PyObject *
@@ -590,9 +570,7 @@
 The factory function inserted in the module dictionary to create PKey\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The PKey object\n\
+@return: The PKey object\n\
 ";
 
 static PyObject *
@@ -614,12 +592,12 @@
 The factory function inserted in the module dictionary to create\n\
 X509Extension objects.\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be\n\
-             typename - ???\n\
-             critical - ???\n\
-             value    - ???\n\
-Returns:   The X509Extension object\n\
+@param typename: The name of the extension to create.\n\
+@type typename: C{str}\n\
+@param critical: A flag indicating whether this is a critical extension.\n\
+@param value: The value of the extension.\n\
+@type value: C{str}\n\
+@return: The X509Extension object\n\
 ";
 
 static PyObject *
@@ -639,10 +617,9 @@
 The factory function inserted in the module dictionary to create NetscapeSPKI\n\
 objects\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty or, optionally\n\
-             enc - Base64 encoded NetscapeSPKI object.\n\
-Returns:   The NetscapeSPKI object\n\
+@param enc: Base64 encoded NetscapeSPKI object.\n\
+@type enc: C{str}\n\
+@return: The NetscapeSPKI object\n\
 ";
 
 static PyObject *
@@ -670,8 +647,8 @@
 static char crypto_X509_verify_cert_error_string_doc[] = "\n\
 Get X509 verify certificate error string.\n\
 \n\
-Arguments: errnum - Error number\n\
-Returns:   Error string as a Python string\n\
+@param errnum: The error number.\n\
+@return: Error string as a Python string\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/netscape_spki.c b/src/crypto/netscape_spki.c
index e9f2553..a0796cb 100644
--- a/src/crypto/netscape_spki.c
+++ b/src/crypto/netscape_spki.c
@@ -52,11 +52,9 @@
 static char crypto_NetscapeSPKI_sign_doc[] = "\n\
 Sign the certificate request using the supplied key and digest\n\
 \n\
-Arguments: self - The NetscapeSPKI object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey   - The key to sign with\n\
-             digest - The message digest to use\n\
-Returns:   None\n\
+@param pkey: The key to sign with\n\
+@param digest: The message digest to use\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -88,11 +86,9 @@
 
 static char crypto_NetscapeSPKI_verify_doc[] = "\n\
 Verifies a certificate request using the supplied public key\n\
- \n\
-Arguments: self - NetscapeSPKI object\n\
-           args - The Python argument tuple, should be:\n\
-             key - a public key\n\
-Returns:   True, if the signature is correct, 0 otherwise.\n\
+\n\
+@param key: a public key\n\
+@return: True if the signature is correct, False otherwise.\n\
 ";
 
 PyObject *
@@ -115,10 +111,8 @@
 
 static char crypto_NetscapeSPKI_b64_encode_doc[] = "\n\
 Generate a base64 encoded string from an SPKI\n\
- \n\
-Arguments: self - NetscapeSPKI object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The base64 encoded string\n\
+\n\
+@return: The base64 encoded string\n\
 ";
 
 PyObject *
@@ -137,9 +131,7 @@
 static char crypto_NetscapeSPKI_get_pubkey_doc[] = "\n\
 Get the public key of the certificate\n\
 \n\
-Arguments: self - The NETSCAPE_SPKI object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The public key\n\
+@return: The public key\n\
 ";
 
 static PyObject *
@@ -163,10 +155,8 @@
 static char crypto_NetscapeSPKI_set_pubkey_doc[] = "\n\
 Set the public key of the certificate\n\
 \n\
-Arguments: self - The Netscape SPKI object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey - The public key\n\
-Returns:   None\n\
+@param pkey: The public key\n\
+@return: None\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/pkcs12.c b/src/crypto/pkcs12.c
index adbd0dc..3fa39aa 100644
--- a/src/crypto/pkcs12.c
+++ b/src/crypto/pkcs12.c
@@ -24,9 +24,7 @@
 static char crypto_PKCS12_get_certificate_doc[] = "\n\
 Return certificate portion of the PKCS12 structure\n\
 \n\
-Arguments: self - The PKCS12 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   X509 object containing the certificate\n\
+@return: X509 object containing the certificate\n\
 ";
 static PyObject *
 crypto_PKCS12_get_certificate(crypto_PKCS12Obj *self, PyObject *args)
@@ -41,9 +39,7 @@
 static char crypto_PKCS12_get_privatekey_doc[] = "\n\
 Return private key portion of the PKCS12 structure\n\
 \n\
-Arguments: self - The PKCS12 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   PKey object containing the private key\n\
+@returns: PKey object containing the private key\n\
 ";
 static PyObject *
 crypto_PKCS12_get_privatekey(crypto_PKCS12Obj *self, PyObject *args)
@@ -58,10 +54,8 @@
 static char crypto_PKCS12_get_ca_certificates_doc[] = "\n\
 Return CA certificates within of the PKCS12 object\n\
 \n\
-Arguments: self - The PKCS12 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   A newly created tuple containing the CA certificates in the chain,\n\
-           if any are present, or None if no CA certificates are present.\n\
+@return: A newly created tuple containing the CA certificates in the chain,\n\
+         if any are present, or None if no CA certificates are present.\n\
 ";
 static PyObject *
 crypto_PKCS12_get_ca_certificates(crypto_PKCS12Obj *self, PyObject *args)
diff --git a/src/crypto/pkcs7.c b/src/crypto/pkcs7.c
index 4a2c066..4ff0b6b 100644
--- a/src/crypto/pkcs7.c
+++ b/src/crypto/pkcs7.c
@@ -14,9 +14,7 @@
 static char crypto_PKCS7_type_is_signed_doc[] = "\n\
 Check if this NID_pkcs7_signed object\n\
 \n\
-Arguments: self - The PKCS7 object\n\
-           args - An empty argument tuple\n\
-Returns:   True if the PKCS7 is of type signed\n\
+@return: True if the PKCS7 is of type signed\n\
 ";
 
 static PyObject *
@@ -34,9 +32,7 @@
 static char crypto_PKCS7_type_is_enveloped_doc[] = "\n\
 Check if this NID_pkcs7_enveloped object\n\
 \n\
-Arguments: self - The PKCS7 object\n\
-           args - An empty argument tuple\n\
-Returns:   True if the PKCS7 is of type enveloped\n\
+@returns: True if the PKCS7 is of type enveloped\n\
 ";
 
 static PyObject *
@@ -54,9 +50,7 @@
 static char crypto_PKCS7_type_is_signedAndEnveloped_doc[] = "\n\
 Check if this NID_pkcs7_signedAndEnveloped object\n\
 \n\
-Arguments: self - The PKCS7 object\n\
-           args - An empty argument tuple\n\
-Returns:   True if the PKCS7 is of type signedAndEnveloped\n\
+@returns: True if the PKCS7 is of type signedAndEnveloped\n\
 ";
 
 static PyObject *
@@ -74,9 +68,7 @@
 static char crypto_PKCS7_type_is_data_doc[] = "\n\
 Check if this NID_pkcs7_data object\n\
 \n\
-Arguments: self - The PKCS7 object\n\
-           args - An empty argument tuple\n\
-Returns:   True if the PKCS7 is of type data\n\
+@return: True if the PKCS7 is of type data\n\
 ";
 
 static PyObject *
@@ -94,9 +86,7 @@
 static char crypto_PKCS7_get_type_name_doc[] = "\n\
 Returns the type name of the PKCS7 structure\n\
 \n\
-Arguments: self - The PKCS7 object\n\
-           args - An empty argument tuple\n\
-Returns:   A string with the typename\n\
+@return: A string with the typename\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/pkey.c b/src/crypto/pkey.c
index fee3e81..3d67cfc 100644
--- a/src/crypto/pkey.c
+++ b/src/crypto/pkey.c
@@ -29,11 +29,9 @@
 static char crypto_PKey_generate_key_doc[] = "\n\
 Generate a key of a given type, with a given number of a bits\n\
 \n\
-Arguments: self - The PKey object\n\
-           args - The Python argument tuple, should be:\n\
-             type - The key type (TYPE_RSA or TYPE_DSA)\n\
-             bits - The number of bits\n\
-Returns:   None\n\
+@param type: The key type (TYPE_RSA or TYPE_DSA)\n\
+@param bits: The number of bits\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -81,9 +79,7 @@
 static char crypto_PKey_bits_doc[] = "\n\
 Returns the number of bits of the key\n\
 \n\
-Arguments: self - The PKey object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns: The number of bits of the key.\n\
+@return: The number of bits of the key.\n\
 ";
 
 static PyObject *
@@ -98,9 +94,7 @@
 static char crypto_PKey_type_doc[] = "\n\
 Returns the type of the key\n\
 \n\
-Arguments: self - The PKey object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns: The type of the key.\n\
+@return: The type of the key.\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/x509.c b/src/crypto/x509.c
index 90a213b..5c5fafb 100644
--- a/src/crypto/x509.c
+++ b/src/crypto/x509.c
@@ -21,9 +21,7 @@
 static char crypto_X509_get_version_doc[] = "\n\
 Return version number of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   Version number as a Python integer\n\
+@return: Version number as a Python integer\n\
 ";
 
 static PyObject *
@@ -38,10 +36,8 @@
 static char crypto_X509_set_version_doc[] = "\n\
 Set version number of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             version - The version number\n\
-Returns:   None\n\
+@param version: The version number\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -61,9 +57,7 @@
 static char crypto_X509_get_serial_number_doc[] = "\n\
 Return serial number of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   Serial number as a Python integer\n\
+@return: Serial number as a Python integer\n\
 ";
 
 static PyObject *
@@ -89,10 +83,8 @@
 static char crypto_X509_set_serial_number_doc[] = "\n\
 Set serial number of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             serial - The serial number\n\
-Returns:   None\n\
+@param serial: The serial number\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -188,9 +180,7 @@
 static char crypto_X509_get_issuer_doc[] = "\n\
 Create an X509Name object for the issuer of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   An X509Name object\n\
+@return: An X509Name object\n\
 ";
 
 static PyObject *
@@ -215,10 +205,9 @@
 static char crypto_X509_set_issuer_doc[] = "\n\
 Set the issuer of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             issuer - The issuer name\n\
-Returns:   None\n\
+@param issuer: The issuer name\n\
+@type issuer: L{X509Name}\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -243,9 +232,7 @@
 static char crypto_X509_get_subject_doc[] = "\n\
 Create an X509Name object for the subject of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   An X509Name object\n\
+@return: An X509Name object\n\
 ";
 
 static PyObject *
@@ -270,10 +257,9 @@
 static char crypto_X509_set_subject_doc[] = "\n\
 Set the subject of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             subject - The subject name\n\
-Returns:   None\n\
+@param subject: The subject name\n\
+@type subject: L{X509Name}\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -298,9 +284,7 @@
 static char crypto_X509_get_pubkey_doc[] = "\n\
 Get the public key of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The public key\n\
+@return: The public key\n\
 ";
 
 static PyObject *
@@ -329,10 +313,8 @@
 static char crypto_X509_set_pubkey_doc[] = "\n\
 Set the public key of the certificate\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey - The public key\n\
-Returns:   None\n\
+@param pkey: The public key\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -380,15 +362,13 @@
 static char crypto_X509_set_notBefore_doc[] = "\n\
 Set the time stamp for when the certificate starts being valid\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             when - A string giving the timestamp, in the format:\n\
+@param when: A string giving the timestamp, in the format:\n\
 \n\
                  YYYYMMDDhhmmssZ\n\
                  YYYYMMDDhhmmss+hhmm\n\
                  YYYYMMDDhhmmss-hhmm\n\
 \n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 static PyObject*
@@ -401,15 +381,13 @@
 static char crypto_X509_set_notAfter_doc[] = "\n\
 Set the time stamp for when the certificate stops being valid\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             when - A string giving the timestamp, in the format:\n\
+@param when: A string giving the timestamp, in the format:\n\
 \n\
                  YYYYMMDDhhmmssZ\n\
                  YYYYMMDDhhmmss+hhmm\n\
                  YYYYMMDDhhmmss-hhmm\n\
 \n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 static PyObject*
@@ -457,10 +435,7 @@
 static char crypto_X509_get_notBefore_doc[] = "\n\
 Retrieve the time stamp for when the certificate starts being valid\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty.\n\
-\n\
-Returns:   A string giving the timestamp, in the format:\n\
+@return: A string giving the timestamp, in the format:\n\
 \n\
                  YYYYMMDDhhmmssZ\n\
                  YYYYMMDDhhmmss+hhmm\n\
@@ -482,10 +457,7 @@
 static char crypto_X509_get_notAfter_doc[] = "\n\
 Retrieve the time stamp for when the certificate stops being valid\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty.\n\
-\n\
-Returns:   A string giving the timestamp, in the format:\n\
+@return: A string giving the timestamp, in the format:\n\
 \n\
                  YYYYMMDDhhmmssZ\n\
                  YYYYMMDDhhmmss+hhmm\n\
@@ -508,21 +480,20 @@
 Change the timestamp for when the certificate starts being valid to the current\n\
 time plus an offset.\n \
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             i - The adjustment\n\
-Returns:   None\n\
+@param amount: The number of seconds by which to adjust the starting validity\n\
+               time.\n\
+@return: None\n\
 ";
 
 static PyObject *
 crypto_X509_gmtime_adj_notBefore(crypto_X509Obj *self, PyObject *args)
 {
-    long i;
+    long amount;
 
-    if (!PyArg_ParseTuple(args, "l:gmtime_adj_notBefore", &i))
+    if (!PyArg_ParseTuple(args, "l:gmtime_adj_notBefore", &amount))
         return NULL;
 
-    X509_gmtime_adj(X509_get_notBefore(self->x509), i);
+    X509_gmtime_adj(X509_get_notBefore(self->x509), amount);
 
     Py_INCREF(Py_None);
     return Py_None;
@@ -531,21 +502,20 @@
 static char crypto_X509_gmtime_adj_notAfter_doc[] = "\n\
 Adjust the time stamp for when the certificate stops being valid\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             i - The adjustment\n\
-Returns:   None\n\
+@param amount: The number of seconds by which to adjust the ending validity\n\
+               time.\n\
+@return: None\n\
 ";
 
 static PyObject *
 crypto_X509_gmtime_adj_notAfter(crypto_X509Obj *self, PyObject *args)
 {
-    long i;
+    long amount;
 
-    if (!PyArg_ParseTuple(args, "l:gmtime_adj_notAfter", &i))
+    if (!PyArg_ParseTuple(args, "l:gmtime_adj_notAfter", &amount))
         return NULL;
 
-    X509_gmtime_adj(X509_get_notAfter(self->x509), i);
+    X509_gmtime_adj(X509_get_notAfter(self->x509), amount);
 
     Py_INCREF(Py_None);
     return Py_None;
@@ -554,11 +524,9 @@
 static char crypto_X509_sign_doc[] = "\n\
 Sign the certificate using the supplied key and digest\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey   - The key to sign with\n\
-             digest - The message digest to use\n\
-Returns:   None\n\
+@param pkey: The key to sign with\n\
+@param digest: The message digest to use\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -601,9 +569,7 @@
 static char crypto_X509_has_expired_doc[] = "\n\
 Check whether the certificate has expired.\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True if the certificate has expired, false otherwise\n\
+@return: True if the certificate has expired, false otherwise\n\
 ";
 
 static PyObject *
@@ -624,9 +590,7 @@
 static char crypto_X509_subject_name_hash_doc[] = "\n\
 Return the hash of the X509 subject.\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The hash of the subject\n\
+@return: The hash of the subject\n\
 ";
 
 static PyObject *
@@ -641,9 +605,7 @@
 static char crypto_X509_digest_doc[] = "\n\
 Return the digest of the X509 object.\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The digest of the object\n\
+@return: The digest of the object\n\
 ";
 
 static PyObject *
@@ -684,10 +646,8 @@
 static char crypto_X509_add_extensions_doc[] = "\n\
 Add extensions to the certificate.\n\
 \n\
-Arguments: self - X509 object\n\
-           args - The Python argument tuple, should be:\n\
-             extensions - a sequence of X509Extension objects\n\
-Returns:   None\n\
+@param extensions: a sequence of X509Extension objects\n\
+@return: None\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/x509ext.c b/src/crypto/x509ext.c
index 84df441..6f31b8e 100644
--- a/src/crypto/x509ext.c
+++ b/src/crypto/x509ext.c
@@ -16,9 +16,7 @@
 static char crypto_X509Extension_get_critical_doc[] = "\n\
 Returns the critical field of the X509Extension\n\
 \n\
-Arguments: self - The X509Extension object\n\
-           args - The argument tuple, should be empty\n\
-Returns: The critical field.\n\
+@return: The critical field.\n\
 ";
 
 static PyObject *
@@ -33,9 +31,7 @@
 static char crypto_X509Extension_get_short_name_doc[] = "\n\
 Returns the short version of the type name of the X509Extension\n\
 \n\
-Arguments: self - The X509Extension object\n\
-           args - The argument tuple, should be empty\n\
-Returns: The short type name.\n\
+@return: The short type name.\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/x509name.c b/src/crypto/x509name.c
index 8871ab1..19c3fe0 100644
--- a/src/crypto/x509name.c
+++ b/src/crypto/x509name.c
@@ -225,11 +225,9 @@
 }
 
 static char crypto_X509Name_hash_doc[] = "\n\
-Return the has value of this name\n\
+Return the hash value of this name\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 /*
@@ -251,11 +249,9 @@
 }
 
 static char crypto_X509Name_der_doc[] = "\n\
-Return the DER encodeing of this name\n\
+Return the DER encoding of this name\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 /*
@@ -278,9 +274,7 @@
 static char crypto_X509Name_get_components_doc[] = "\n\
 Returns the split-up components of this name.\n\
 \n\
-Arguments: self - The X509 object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   List of tuples (name, value).\n\
+@return: List of tuples (name, value).\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/x509req.c b/src/crypto/x509req.c
index bb6385f..93865ce 100644
--- a/src/crypto/x509req.c
+++ b/src/crypto/x509req.c
@@ -15,9 +15,7 @@
 static char crypto_X509Req_get_subject_doc[] = "\n\
 Create an X509Name object for the subject of the certificate request\n\
 \n\
-Arguments: self - The X509Req object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   An X509Name object\n\
+@return: An X509Name object\n\
 ";
 
 static PyObject *
@@ -45,9 +43,7 @@
 static char crypto_X509Req_get_pubkey_doc[] = "\n\
 Get the public key from the certificate request\n\
 \n\
-Arguments: self - The X509Req object\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   The public key\n\
+@return: The public key\n\
 ";
 
 static PyObject *
@@ -76,10 +72,8 @@
 static char crypto_X509Req_set_pubkey_doc[] = "\n\
 Set the public key of the certificate request\n\
 \n\
-Arguments: self - The X509Req object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey - The public key to use\n\
-Returns:   None\n\
+@param pkey: The public key to use\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -103,11 +97,9 @@
 static char crypto_X509Req_sign_doc[] = "\n\
 Sign the certificate request using the supplied key and digest\n\
 \n\
-Arguments: self - The X509Req object\n\
-           args - The Python argument tuple, should be:\n\
-             pkey   - The key to sign with\n\
-             digest - The message digest to use\n\
-Returns:   None\n\
+@param pkey: The key to sign with\n\
+@param digest: The message digest to use\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -149,11 +141,9 @@
  
 static char crypto_X509Req_verify_doc[] = "\n\
 Verifies a certificate request using the supplied public key\n\
- \n\
-Arguments: self - X509Req object\n\
-           args - The Python argument tuple, should be:\n\
-             key - a public key\n\
-Returns:   True, if the signature is correct, 0 otherwise.\n\
+\n\
+@param key: a public key\n\
+@return: True if the signature is correct, False otherwise.\n\
 ";
 
 PyObject *
@@ -180,10 +170,8 @@
 static char crypto_X509Req_add_extensions_doc[] = "\n\
 Add extensions to the request.\n\
 \n\
-Arguments: self - X509Req object\n\
-           args - The Python argument tuple, should be:\n\
-             extensions - a sequence of X509Extension objects\n\
-Returns:   None\n\
+@param extensions: a sequence of X509Extension objects\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -243,10 +231,8 @@
 Set the version subfield (RFC 2459, section 4.1.2.1) of the certificate\n\
 request.\n\
 \n\
-Arguments: self - X509Req object\n\
-           args - The Python argument tuple, should be:\n\
-             version - The version number\n\
-Returns:   None\n\
+@param version: The version number\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -270,9 +256,7 @@
 Get the version subfield (RFC 2459, section 4.1.2.1) of the certificate\n\
 request.\n\
 \n\
-Arguments: self - X509Req object\n\
-           args - The Python argument tuple, should be empty.\n\
-Returns:   an integer giving the value of the version subfield\n\
+@return: an integer giving the value of the version subfield\n\
 ";
 
 static PyObject *
diff --git a/src/crypto/x509store.c b/src/crypto/x509store.c
index 442c2d5..6bf1310 100644
--- a/src/crypto/x509store.c
+++ b/src/crypto/x509store.c
@@ -13,10 +13,8 @@
 static char crypto_X509Store_add_cert_doc[] = "\n\
 Add a certificate\n\
 \n\
-Arguments: self - The X509Store object\n\
-           args - The Python argument tuple, should be:\n\
-             cert - The certificate to add\n\
-Returns:   None\n\
+@param cert: The certificate to add\n\
+@return: None\n\
 ";
 
 static PyObject *
diff --git a/src/rand/rand.c b/src/rand/rand.c
index ff89ebb..f1c8440 100644
--- a/src/rand/rand.c
+++ b/src/rand/rand.c
@@ -30,11 +30,9 @@
 static char rand_add_doc[] = "\n\
 Add data with a given entropy to the PRNG\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             buffer  - Buffer with random data\n\
-             entropy - The entropy (in bytes) measurement of the buffer\n\
-Returns:   None\n\
+@param buffer: Buffer with random data\n\
+@param entropy: The entropy (in bytes) measurement of the buffer\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -56,10 +54,8 @@
 static char rand_seed_doc[] = "\n\
 Alias for rand_add, with entropy equal to length\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             buffer - Buffer with random data\n\
-Returns:   None\n\
+@param buffer: Buffer with random data\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -80,9 +76,7 @@
 static char rand_status_doc[] = "\n\
 Retrieve the status of the PRNG\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   True if the PRNG is seeded enough, false otherwise\n\
+@return: True if the PRNG is seeded enough, false otherwise\n\
 ";
 
 static PyObject *
@@ -99,9 +93,7 @@
 Add the current contents of the screen to the PRNG state. Availability:\n\
 Windows.\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -121,12 +113,10 @@
 PRNG. I haven't found any problems when the socket is missing, the function\n\
 just returns 0.\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             path  - The path to the EGD socket\n\
-             bytes - (optional) The number of bytes to read, default is 255\n\
-Returns:   The number of bytes read (NB: a value of 0 isn't necessarily an\n\
-           error, check rand.status())\n\
+@param path: The path to the EGD socket\n\
+@param bytes: (optional) The number of bytes to read, default is 255\n\
+@returns: The number of bytes read (NB: a value of 0 isn't necessarily an\n\
+          error, check rand.status())\n\
 ";
 
 static PyObject *
@@ -144,9 +134,7 @@
 static char rand_cleanup_doc[] = "\n\
 Erase the memory used by the PRNG.\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be empty\n\
-Returns:   None\n\
+@return: None\n\
 ";
 
 static PyObject *
@@ -164,12 +152,10 @@
 static char rand_load_file_doc[] = "\n\
 Seed the PRNG with data from a file\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             filename - The file to read data from\n\
-             maxbytes - (optional) The number of bytes to read, default is\n\
-                        to read the entire file\n\
-Returns:   The number of bytes read\n\
+@param filename: The file to read data from\n\
+@param maxbytes: (optional) The number of bytes to read, default is\n\
+                 to read the entire file\n\
+@return: The number of bytes read\n\
 ";
 
 static PyObject *
@@ -187,10 +173,8 @@
 static char rand_write_file_doc[] = "\n\
 Save PRNG state to a file\n\
 \n\
-Arguments: spam - Always NULL\n\
-           args - The Python argument tuple, should be:\n\
-             filename - The file to write data to\n\
-Returns:   The number of bytes written\n\
+@param filename: The file to write data to\n\
+@return: The number of bytes written\n\
 ";
 
 static PyObject *
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 *