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 *