Source documentation update, including a short HACKING file.

3 files changed, 43 insertions, 51 deletions

diff --git a/protocols/bee.h b/protocols/bee.h
index 4b6a1f4a..a8517f2e 100644
--- a/protocols/bee.h
+++ b/protocols/bee.h
@@ -31,18 +31,24 @@ struct groupchat;
 
 typedef struct bee
 {
+	/* Settings. See set.h for how these work. The UI can add its
+	   own settings here. */
 	struct set *set;
 	
-	GSList *users;
-	GSList *groups;
+	GSList *users;  /* struct bee_user */
+	GSList *groups; /* struct bee_group */
 	struct account *accounts; /* TODO(wilmer): Use GSList here too? */
 	
 	/* Symbolic, to refer to the local user (who has no real bee_user
 	   object). Not to be used by anything except so far imcb_chat_add/
-	   remove_buddy(). This seems slightly cleaner than abusing NULL. */
+	   remove_buddy(). */
 	struct bee_user *user;
 	
+	/* Fill in the callbacks for events you care about. */
 	const struct bee_ui_funcs *ui;
+	
+	/* And this one will be passed to every callback for any state the
+	   UI may want to keep. */
 	void *ui_data;
 } bee_t;
 
@@ -65,18 +71,21 @@ typedef struct bee_user
 	struct bee_group *group;
 
 	bee_user_flags_t flags;
-	char *status;
-	char *status_msg;
+	char *status;     /* NULL means available, anything else is an away state. */
+	char *status_msg; /* Status and/or away message. */
 	
+	/* Set using imcb_buddy_times(). */
 	time_t login_time, idle_time;
 	
 	bee_t *bee;
 	void *ui_data;
 } bee_user_t;
 
+/* This one's mostly used so save space and make it easier (cheaper) to
+   compare groups of contacts, etc. */
 typedef struct bee_group
 {
-	char *key;
+	char *key;  /* Lower case version of the name. */
 	char *name;
 } bee_group_t;
 
@@ -87,15 +96,23 @@ typedef struct bee_ui_funcs
 	
 	gboolean (*user_new)( bee_t *bee, struct bee_user *bu );
 	gboolean (*user_free)( bee_t *bee, struct bee_user *bu );
+	/* Set the fullname first, then call this one to notify the UI. */
 	gboolean (*user_fullname)( bee_t *bee, bee_user_t *bu );
 	gboolean (*user_nick_hint)( bee_t *bee, bee_user_t *bu, const char *hint );
+	/* Notify the UI when an existing user is moved between groups. */
 	gboolean (*user_group)( bee_t *bee, bee_user_t *bu );
+	/* State info is already updated, old is provided in case the UI needs a diff. */
 	gboolean (*user_status)( bee_t *bee, struct bee_user *bu, struct bee_user *old );
+	/* On every incoming message. sent_at = 0 means unknown. */
 	gboolean (*user_msg)( bee_t *bee, bee_user_t *bu, const char *msg, time_t sent_at );
+	/* Flags currently defined (OPT_TYPING/THINKING) in nogaim.h. */
 	gboolean (*user_typing)( bee_t *bee, bee_user_t *bu, guint32 flags );
 	
+	/* Called at creation time. Don't show to the user until s/he is
+	   added using chat_add_user().  UI state can be stored via c->data. */
 	gboolean (*chat_new)( bee_t *bee, struct groupchat *c );
 	gboolean (*chat_free)( bee_t *bee, struct groupchat *c );
+	/* System messages of any kind. */
 	gboolean (*chat_log)( bee_t *bee, struct groupchat *c, const char *text );
 	gboolean (*chat_msg)( bee_t *bee, struct groupchat *c, bee_user_t *bu, const char *msg, time_t sent_at );
 	gboolean (*chat_add_user)( bee_t *bee, struct groupchat *c, bee_user_t *bu );
@@ -134,18 +151,25 @@ G_MODULE_EXPORT void imcb_buddy_times( struct im_connection *ic, const char *han
 G_MODULE_EXPORT void imcb_buddy_msg( struct im_connection *ic, const char *handle, char *msg, guint32 flags, time_t sent_at );
 
 /* bee_chat.c */
-#if 0
-struct groupchat *imcb_chat_new( struct im_connection *ic, const char *handle );
-void imcb_chat_name_hint( struct groupchat *c, const char *name );
-void imcb_chat_free( struct groupchat *c );
-void imcb_chat_msg( struct groupchat *c, const char *who, char *msg, uint32_t flags, time_t sent_at );
-void imcb_chat_log( struct groupchat *c, char *format, ... );
-void imcb_chat_topic( struct groupchat *c, char *who, char *topic, time_t set_at );
-void imcb_chat_add_buddy( struct groupchat *b, const char *handle );
-void imcb_chat_remove_buddy( struct groupchat *b, const char *handle, const char *reason );
-static int remove_chat_buddy_silent( struct groupchat *b, const char *handle );
-#endif
-int bee_chat_msg( bee_t *bee, struct groupchat *c, const char *msg, int flags );
-struct groupchat *bee_chat_by_title( bee_t *bee, struct im_connection *ic, const char *title );
+/* These two functions are to create a group chat.
+ * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
+ *   channel name on IRC.
+ * - After you have a groupchat pointer, you should add the handles, finally  
+ *   the user her/himself. At that point the group chat will be visible to the
+ *   user, too. */
+G_MODULE_EXPORT struct groupchat *imcb_chat_new( struct im_connection *ic, const char *handle );
+G_MODULE_EXPORT void imcb_chat_name_hint( struct groupchat *c, const char *name );
+G_MODULE_EXPORT void imcb_chat_free( struct groupchat *c );
+/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
+G_MODULE_EXPORT void imcb_chat_msg( struct groupchat *c, const char *who, char *msg, guint32 flags, time_t sent_at );
+/* System messages specific to a groupchat, so they can be displayed in the right context. */
+G_MODULE_EXPORT void imcb_chat_log( struct groupchat *c, char *format, ... );
+/* To tell BitlBee 'who' changed the topic of 'c' to 'topic'. */
+G_MODULE_EXPORT void imcb_chat_topic( struct groupchat *c, char *who, char *topic, time_t set_at );
+G_MODULE_EXPORT void imcb_chat_add_buddy( struct groupchat *c, const char *handle );
+/* To remove a handle from a group chat. Reason can be NULL. */
+G_MODULE_EXPORT void imcb_chat_remove_buddy( struct groupchat *c, const char *handle, const char *reason );
+G_MODULE_EXPORT int bee_chat_msg( bee_t *bee, struct groupchat *c, const char *msg, int flags );
+G_MODULE_EXPORT struct groupchat *bee_chat_by_title( bee_t *bee, struct im_connection *ic, const char *title );
 
 #endif /* __BEE_H__ */
diff --git a/protocols/nogaim.c b/protocols/nogaim.c
index e628126f..d8c7d05a 100644
--- a/protocols/nogaim.c
+++ b/protocols/nogaim.c
@@ -288,17 +288,6 @@ void imcb_connected( struct im_connection *ic )
 	
 	if( ic->bee->ui->imc_connected )
 		ic->bee->ui->imc_connected( ic );
-	
-	/*
-	for( c = irc->chatrooms; c; c = c->next )
-	{
-		if( c->acc != ic->acc )
-			continue;
-		
-		if( set_getbool( &c->set, "auto_join" ) )
-			chat_join( irc, c, NULL );
-	}
-	*/
 }
 
 gboolean auto_reconnect( gpointer data, gint fd, b_input_condition cond )
diff --git a/protocols/nogaim.h b/protocols/nogaim.h
index 46f6535a..a12ce89b 100644
--- a/protocols/nogaim.h
+++ b/protocols/nogaim.h
@@ -304,27 +304,6 @@ G_MODULE_EXPORT void imcb_buddy_typing( struct im_connection *ic, char *handle,
 G_MODULE_EXPORT struct bee_user *imcb_buddy_by_handle( struct im_connection *ic, const char *handle );
 G_MODULE_EXPORT void imcb_clean_handle( struct im_connection *ic, char *handle );
 
-/* Groupchats */
-G_MODULE_EXPORT void imcb_chat_invited( struct im_connection *ic, char *handle, char *who, char *msg, GList *data );
-/* These two functions are to create a group chat.
- * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
- *   channel name on IRC.
- * - After you have a groupchat pointer, you should add the handles, finally
- *   the user her/himself. At that point the group chat will be visible to the
- *   user, too. */
-G_MODULE_EXPORT struct groupchat *imcb_chat_new( struct im_connection *ic, const char *handle );
-G_MODULE_EXPORT void imcb_chat_name_hint( struct groupchat *c, const char *name );
-G_MODULE_EXPORT void imcb_chat_add_buddy( struct groupchat *b, const char *handle );
-/* To remove a handle from a group chat. Reason can be NULL. */
-G_MODULE_EXPORT void imcb_chat_remove_buddy( struct groupchat *b, const char *handle, const char *reason );
-/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
-G_MODULE_EXPORT void imcb_chat_msg( struct groupchat *c, const char *who, char *msg, uint32_t flags, time_t sent_at );
-/* System messages specific to a groupchat, so they can be displayed in the right context. */
-G_MODULE_EXPORT void imcb_chat_log( struct groupchat *c, char *format, ... ) G_GNUC_PRINTF( 2, 3 );
-/* To tell BitlBee 'who' changed the topic of 'c' to 'topic'. */
-G_MODULE_EXPORT void imcb_chat_topic( struct groupchat *c, char *who, char *topic, time_t set_at );
-G_MODULE_EXPORT void imcb_chat_free( struct groupchat *c );
-
 /* Actions, or whatever. */
 int imc_away_send_update( struct im_connection *ic );
 int imc_chat_msg( struct groupchat *c, char *msg, int flags );