Update documentation

IRCClient/IRCClientSession.h

@@ -22,14 +22,18 @@
  * IRCClientSession *session = [[IRCClientSession alloc] init];
  * MyIRCClientSessionDelegate *controller = [[MyIRCClientSessionDelegate alloc] init];
  * 
- * [session setDelegate:controller];
- * [controller setSession:session];
+ * session.delegate = controller;
+ * controller.session = session;
  * 
- * [session setServer:@"irc.dal.net"];
- * [session setPort:@"6667"];
- * [session setNickname:@"test"];
- * [session setUsername:@"test"];
- * [session setRealname:@"test"];
+ * NSData *server = [NSData dataWithBytes:@"chat.freenode.net".UTF8String length:strlen(@"chat.freenode.net".UTF8String.length) + 1];
+ * NSUinteger port = 6665;
+ * NSData *nickname = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
+ * NSData *username = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
+ * NSData *realname = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
+ *
+ * [session setServer:server];
+ * [session setPort:port];
+ * [session setNickname:nickname username:username realname:realname];
  * [session connect];
  * 
  * [session run]; //starts the thread
@@ -37,8 +41,11 @@
  * 
  * \section author Author, copyright, support.
  *
- * If you have any questions, bug reports, suggestions regarding libircclient 
- * or the IRCClient framework, please visit http://libircclient.sourceforge.net
+ * If you have questions, bug reports, or suggestions regarding IRCClient,
+ * find Obormot on the Freenode IRC network.
+ *
+ * If you have any questions, bug reports, suggestions regarding libircclient,
+ * please visit http://libircclient.sourceforge.net
  *
  * <PRE>
  * libircclient Copyright (C) 2004-2009 Georgy Yunaev gyunaev@ulduzsoft.com
@@ -64,12 +71,13 @@
  *	@brief Represents a connected IRC Session.
  *
  *	IRCClientSession represents a single connection to an IRC server. On initialising
- *  the object, and setting the delegate, server, port, password, nickname, username and realname
- *	properties, you call the connect: and run: methods to connect to the IRC server
- *	and start a new thread.
+ *  the object, and setting the delegate, server, port, and password (if required)
+ *	properties, and setting the nickname, username and realname using the
+ *	setNickname:username:realname: method, you call the connect: and run: methods 
+ *	to connect to the IRC server and start a new thread.
  *
- *	This thread then sends messages back to the main runloop to the IRC server delegate,
- *	or to the IRCClientChannel delegate as required.
+ *	This thread then sends messages to the IRC server delegate,
+ *	or to the IRCClientChannel delegate, as required.
  */
 
 /**********************************************/
@@ -90,7 +98,10 @@
  */
 @property (assign) NSUInteger sessionID;
 
-/** The version string for the client to send back on CTCP VERSION requests */
+/** The version string for the client to send back on CTCP VERSION requests.
+	There is usually no reason to set this, as IRCClient correctly sets its
+	own version string automatically, but this can be any string you like.
+ */
 @property (copy) NSData *version;
 
 /** IRC server to connect to */
@@ -116,8 +127,10 @@
 
 /** The suggested text encoding for messages on this server.
  
-	This concerns messages received via PRIVMSG and NOTICE, and TOPIC in a channel.
-	It also affects what encoding reasons given for QUIT messages are assumed to be in.
+	This is almost entirely irrelevant (except for CTCP TIME replies), as 
+	all messages and other strings are taken and returned as C strings
+	encapsulated in NSData objects. This property is for your convenience.
+ 
 	You may change this at any time.
  */
 @property (assign) NSStringEncoding encoding;
@@ -271,8 +284,22 @@
 
 @end
 
+/*************************************/
+#pragma mark - Useful helper functions
+/*************************************/
+
+/**	Returns the nick part of a nick!user@host string.
+ */
 NSData* getNickFromNickUserHost(NSData *nuh);
 
+/**	Returns the user part of a nick!user@host string.
+	Returns nil if the user component can't be found (i.e. if the passed string
+	is not, in fact, in nick!user@host format).
+ */
 NSData* getUserFromNickUserHost(NSData *nuh);
 
+/**	Returns the host part of a nick!user@host string.
+	Returns nil if the host component can't be found (i.e. if the passed string
+	is not, in fact, in nick!user@host format).
+ */
 NSData* getHostFromNickUserHost(NSData *nuh);

IRCClient/IRCClientSession.m

@@ -156,7 +156,7 @@ static NSDictionary* ircNumericCodeList;
 		unsigned int high, low;
 		irc_get_version (&high, &low);
 		
-		NSString* versionString = [NSString stringWithFormat:@"IRCClient Framework v%s (Said Achmiz) - libirc v%d.%d (George Yunaev)", IRCCLIENTVERSION, high, low];
+		NSString* versionString = [NSString stringWithFormat:@"IRCClient Framework v%s (Said Achmiz) - libirc v%d.%d (Georgy Yunaev)", IRCCLIENTVERSION, high, low];
 		_version = [NSData dataWithBytes:versionString.UTF8String length:versionString.length];
 		
 		_channels = [[NSMutableDictionary alloc] init];
@@ -543,7 +543,7 @@ NSData* getNickFromNickUserHost(NSData *nuh)
 	[nuh getBytes:nick_user_host_buf];
 	
 	char *nick_buf;
-	nick_buf = strtok(nick_user_host_buf, "!@");
+	nick_buf = strtok(nick_user_host_buf, "!");
 	
 	NSData* nick = (nick_buf != NULL) ? [NSData dataWithBytes:nick_buf length:strlen(nick_buf) + 1] : nil;
 	
@@ -558,8 +558,8 @@ NSData* getUserFromNickUserHost(NSData *nuh)
 	[nuh getBytes:nick_user_host_buf];
 	
 	char *nick_buf, *user_buf;
-	nick_buf = strtok(nick_user_host_buf, "!@");
-	user_buf = strtok(NULL, "!@");
+	nick_buf = strtok(nick_user_host_buf, "!");
+	user_buf = strtok(NULL, "@");
 	
 	NSData* user = (user_buf != NULL) ? [NSData dataWithBytes:user_buf length:strlen(user_buf) + 1] : nil;
 	
@@ -574,9 +574,9 @@ NSData* getHostFromNickUserHost(NSData *nuh)
 	[nuh getBytes:nick_user_host_buf];
 	
 	char *nick_buf, *user_buf, *host_buf;
-	nick_buf = strtok(nick_user_host_buf, "!@");
-	user_buf = strtok(NULL, "!@");
-	host_buf = strtok(NULL, "!@");
+	nick_buf = strtok(nick_user_host_buf, "!");
+	user_buf = strtok(NULL, "@");
+	host_buf = strtok(NULL, "");
 	
 	NSData* host = (host_buf != NULL) ? [NSData dataWithBytes:host_buf length:strlen(host_buf) + 1] : nil;
 	

README

@@ -2,7 +2,7 @@ This is a modified version of the IRCClient framework by Nathan Ollerenshaw. I
 
 - Said Achmiz
 
-—
+---
 
 ADDING IRCCLIENT TO YOUR APPLICATION
 (using Xcode)
@@ -32,11 +32,23 @@ ADDING IRCCLIENT TO YOUR APPLICATION
 
 6. Import IRCClient’s API into your code using “#import <IRCClient/IRCClient.h>”
 
-—
+---
 
 See the following header files for documentation:
 
 IRCClientSession.h
 IRCClientSessionDelegate.h
 IRCClientChannel.h
-IRCClientChannelDelegate.h
+IRCClientChannelDelegate.h
+
+---
+
+NOTE on strings:
+
+IRCClient stores and passes all strings (messages, nicks, channel names, mode strings, channel topics, etc.) as NSData objects, which contain null-terminated C strings. Values passed to framework methods (such as the IRC commands) should also be in this format[1]. This means that IRCClient is encoding-agnostic[2]; it is up to you to pass it properly encoded C-string representations of your text strings, and it is also up to you to select an appropriate encoding for display or other handling of received strings, as necessary. The 'encoding' property of IRCClientSession and IRCClientChannel may be useful in this regard (i.e. for the convenience associating a server's or channel's preferred encoding with the relevant server or channel object), although note that this property is almost entirely epiphenomenal[3].
+
+[1] Although note that if you pass unterminated strings instead, IRCClient will add the null termination for you - but there is a slight performance penalty for this, so be sure to null-terminate the contents of your NSData objects, for optimal performance.
+
+[2] Of course, IRCClient does not support UTF-16 nor any other non-8-bit encoding (since the byte representations of such encodings may contain nulls, and therefore cannot be used as C strings), but the IRC protocol does not support such encodings either.
+
+[3] The 'encoding' property of IRCClientSession does have one effect: it controls the encoding used by replies to CTCP TIME requests.