Added some (more) comments to .h files in lib/ and some minor fixes/cleanups.

6 files changed, 97 insertions, 16 deletions

diff --git a/doc/user-guide/commands.xml b/doc/user-guide/commands.xml
index fd855360..0016d190 100644
--- a/doc/user-guide/commands.xml
+++ b/doc/user-guide/commands.xml
@@ -745,6 +745,10 @@
 			<para>
 				This command allows to set the friendly name of an im account. If no new name is specified the command will report the current name. When the name contains spaces, don't forget to quote the whole nick in double quotes. Currently this command is only supported by the MSN protocol.
 			</para>
+
+			<para>
+				It is recommended to use the per-account <emphasis>display_name</emphasis> setting to read and change this information. The <emphasis>nick</emphasis> command is deprecated.
+			</para>
 		</description>
 
 		<ircexample>
diff --git a/irc.c b/irc.c
index fcb59c86..0373f176 100644
--- a/irc.c
+++ b/irc.c
@@ -651,7 +651,6 @@ void irc_names( irc_t *irc, char *channel )
 	else if( ( c = conv_findchannel( channel ) ) )
 	{
 		GList *l;
-		char *ops = set_getstr( &irc->set, "ops" );
 		
 		/* root and the user aren't in the channel userlist but should
 		   show up in /NAMES, so list them first: */
diff --git a/lib/events.h b/lib/events.h
index 781fca6a..0588547f 100644
--- a/lib/events.h
+++ b/lib/events.h
@@ -19,11 +19,17 @@
  *
  */
 
-/*
- * Split off the event handling things from proxy.[ch] (and adding timer
- * stuff. This to allow BitlBee to use other libs than GLib for event
- * handling.
- */
+/* This stuff used to be in proxy.c too, but I split it off so BitlBee can
+   use other libraries (like libevent) to handle events. proxy.c is one very
+   nice piece of work from Gaim. It connects to a TCP server in the back-
+   ground and calls a callback function once the connection is ready to use.
+   This function (proxy_connect()) can be found in proxy.c. (It also
+   transparently handles HTTP/SOCKS proxies, when necessary.)
+   
+   This file offers some extra event handling toys, which will be handled
+   by GLib or libevent. The advantage of using libevent is that it can use
+   more advanced I/O polling functions like epoll() in recent Linux
+   kernels. This should improve BitlBee's scalability. */
 
 
 #ifndef _EVENTS_H_
@@ -38,12 +44,15 @@
 #include <glib.h>
 #include <gmodule.h>
 
+/* The conditions you can pass to gaim_input_add()/that will be passed to
+   the given callback function. */
 typedef enum {
 	GAIM_INPUT_READ = 1 << 1,
 	GAIM_INPUT_WRITE = 1 << 2
 } b_input_condition;
 typedef gboolean (*b_event_handler)(gpointer data, gint fd, b_input_condition cond);
 
+/* For internal use. */
 #define GAIM_READ_COND  (G_IO_IN | G_IO_HUP | G_IO_ERR)
 #define GAIM_WRITE_COND (G_IO_OUT | G_IO_HUP | G_IO_ERR | G_IO_NVAL)
 #define GAIM_ERR_COND   (G_IO_HUP | G_IO_ERR | G_IO_NVAL)
@@ -51,14 +60,26 @@ typedef gboolean (*b_event_handler)(gpointer data, gint fd, b_input_condition co
 // #define event_debug( x... ) printf( x )
 #define event_debug( x... )
 
+/* Call this once when the program starts. It'll initialize the event handler
+   library (if necessary) and then return immediately. */
 G_MODULE_EXPORT void b_main_init();
+
+/* This one enters the event loop. It shouldn't return until one of the event
+   handlers calls b_main_quit(). */
 G_MODULE_EXPORT void b_main_run();
 G_MODULE_EXPORT void b_main_quit();
 
+
+/* Add event handlers (for I/O or a timeout). The event handler will be called
+   every time the event "happens", until your event handler returns FALSE (or
+   until you remove it using b_event_remove(). As usual, the data argument
+   can be used to pass your own data to the event handler. */
 G_MODULE_EXPORT gint b_input_add(int fd, b_input_condition cond, b_event_handler func, gpointer data);
 G_MODULE_EXPORT gint b_timeout_add(gint timeout, b_event_handler func, gpointer data);
 G_MODULE_EXPORT void b_event_remove(gint id);
 
+/* For now, closesocket() is only a function when using libevent. With GLib
+   it's a preprocessor macro. */
 #ifdef EVENTS_LIBEVENT
 G_MODULE_EXPORT void closesocket(int fd);
 #endif
diff --git a/lib/http_client.h b/lib/http_client.h
index 50ee80cf..78d6dbd1 100644
--- a/lib/http_client.h
+++ b/lib/http_client.h
@@ -23,24 +23,48 @@
   Suite 330, Boston, MA  02111-1307  USA
 */
 
-#include <glib.h>
+/* http_client allows you to talk (asynchronously, again) to HTTP servers.
+   In the "background" it will send the whole query and wait for a complete
+   response to come back. Right now it's only used by the MSN Passport
+   authentication code, but it might be useful for other things too (for
+   example the AIM usericon patch uses this so icons can be stored on
+   webservers instead of the local filesystem).
+   
+   Didn't test this too much, but it seems to work well. Just don't look
+   at the code that handles HTTP 30x redirects. ;-) The function is
+   probably not very useful for downloading lots of data since it keeps 
+   everything in a memory buffer until the download is completed (and
+   can't pass any data or whatever before then). It's very useful for
+   doing quick requests without blocking the whole program, though. */
 
+#include <glib.h>
 #include "ssl_client.h"
 
 struct http_request;
 
+/* Your callback function should look like this: */
 typedef void (*http_input_function)( struct http_request * );
 
+/* This structure will be filled in by the http_dorequest* functions, and
+   it will be passed to the callback function. Use the data field to add
+   your own data. */
 struct http_request
 {
-	char *request;
-	int request_length;
-	int status_code;
-	char *status_string;
+	char *request;          /* The request to send to the server. */
+	int request_length;     /* Its size. */
+	int status_code;        /* The numeric HTTP status code. (Or -1
+	                           if something really went wrong) */
+	char *status_string;    /* The error text. */
 	char *reply_headers;
 	char *reply_body;
-	int body_size;
-	int finished;
+	int body_size;          /* The number of bytes in reply_body. */
+	int finished;           /* Set to non-0 if the request was completed
+	                           successfully. */
+	
+	http_input_function func;
+	gpointer data;
+	
+	/* Please don't touch the things down here, you shouldn't need them. */
 	
 	void *ssl;
 	int fd;
@@ -48,10 +72,11 @@ struct http_request
 	int inpa;
 	int bytes_written;
 	int bytes_read;
-	
-	http_input_function func;
-	gpointer data;
 };
 
+/* The _url variant is probably more useful than the raw version. The raw
+   version is probably only useful if you want to do POST requests or if
+   you want to add some extra headers. As you can see, HTTPS connections
+   are also supported (using ssl_client). */
 void *http_dorequest( char *host, int port, int ssl, char *request, http_input_function func, gpointer data );
 void *http_dorequest_url( char *url_string, http_input_function func, gpointer data );
diff --git a/lib/rc4.h b/lib/rc4.h
index 6c9ea6b9..2d4d3cc8 100644
--- a/lib/rc4.h
+++ b/lib/rc4.h
@@ -22,6 +22,8 @@
 \***************************************************************************/
 
 
+/* See rc4.c for more information. */
+
 struct rc4_state
 {
 	unsigned char S[256];
diff --git a/lib/ssl_client.h b/lib/ssl_client.h
index 1a9c79e9..964caee4 100644
--- a/lib/ssl_client.h
+++ b/lib/ssl_client.h
@@ -23,20 +23,50 @@
   Suite 330, Boston, MA  02111-1307  USA
 */
 
+/* ssl_client makes it easier to open SSL connections to servers. (It
+   doesn't offer SSL server functionality yet, but it could be useful
+   to add it later.) Different ssl_client modules are available, and
+   ssl_client tries to make them all behave the same. It's very simple
+   and basic, it just imitates the proxy_connect() function from the
+   Gaim libs and passes the socket to the program once the handshake
+   is completed. */
+
 #include <glib.h>
 #include "proxy.h"
 
+/* Some generic error codes. Especially SSL_AGAIN is important if you
+   want to do asynchronous I/O. */
 #define SSL_OK            0
 #define SSL_NOHANDSHAKE   1
 #define SSL_AGAIN         2
 
 extern int ssl_errno;
 
+/* This is what your callback function should look like. */
 typedef gboolean (*ssl_input_function)(gpointer, void*, b_input_condition);
 
+
+/* Connect to host:port, call the given function when the connection is
+   ready to be used for SSL traffic. This is all done asynchronously, no
+   blocking I/O! (Except for the DNS lookups, for now...) */
 G_MODULE_EXPORT void *ssl_connect( char *host, int port, ssl_input_function func, gpointer data );
+
+/* Obviously you need special read/write functions to read data. */
 G_MODULE_EXPORT int ssl_read( void *conn, char *buf, int len );
 G_MODULE_EXPORT int ssl_write( void *conn, const char *buf, int len );
+
+/* Abort the SSL connection and disconnect the socket. Do not use close()
+   directly, both the SSL library and the peer will be unhappy! */
 G_MODULE_EXPORT void ssl_disconnect( void *conn_ );
+
+/* Get the fd for this connection, you will usually need it for event
+   handling. */
 G_MODULE_EXPORT int ssl_getfd( void *conn );
+
+/* This function returns GAIM_INPUT_READ/WRITE. With SSL connections it's
+   possible that something has to be read while actually were trying to
+   write something (think about key exchange/refresh/etc). So when an
+   SSL operation returned SSL_AGAIN, *always* use this function when
+   adding an event handler to the queue. (And it should perform exactly
+   the same action as the handler that just received the SSL_AGAIN.) */
 G_MODULE_EXPORT b_input_condition ssl_getdirection( void *conn );