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)