Change docstrings from being C programmer oriented to being Python programmer oriented
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)