Update the README, and add some ascii-art to libmatrix.h

... because I have a useful drawing on my desk, and it's no use to anyone else
there.

2 files changed, 84 insertions, 4 deletions

diff --git a/README.md b/README.md
index 32f79f9..ff74a19 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,8 @@ implemented. In particular, sending and receiving messages is supported, but
 only for rooms you have already joined (using a different client).
 
 The following are not yet supported:
+ * Sending invitations
+ * Creating new rooms (and one-to-one chats)
  * Presence indication
  * Typing indication
  * Videos/images in messages
@@ -20,9 +22,6 @@ The following are not yet supported:
  * Room topics
  * Voice/video calling
 
-The plugin requires a homeserver running the v2_alpha API, which is not
-(currently) the case for the matrix.org homeserver. You will therefore need to
-run your own homeserver from the 'develop' branch of synapse.
 
 # Installation
 
@@ -47,9 +46,19 @@ You will then need to restart Pidgin, after which you should be able to add a
 
 # Usage
 
-* Open the 'Manage accounts' dialog (under the 'Accounts' menu) and click 'Add'.
+* Open the 'Manage accounts' dialog (under the 'Accounts' menu) and click 
+  'Add'.
 * If the plugin was loaded successfully, you will be able to select 'Matrix'
   from the 'Protocol' dropdown.
 * Enter your matrix ID on the homeserver (e.g. '@bob:matrix.org' or 'bob') as
   the 'username', and the password in the 'password' field.
 * On the 'Advanced' tab, enter the URL of your homeserver.
+
+
+The Advanced account option 'On reconnect, replay recent messages from joined
+rooms' is set by default. This means that pidgin will show the last few 
+messages for each room each time it starts.  If this option is unticked, only
+new messages will be received.  This option requires a homeserver running the 
+v2_alpha API, which is not (currently) the case for the matrix.org homeserver.
+You will therefore need to run your own homeserver from the 'develop' branch 
+of synapse.
diff --git a/libmatrix.h b/libmatrix.h
index 486d0b3..ab766a1 100644
--- a/libmatrix.h
+++ b/libmatrix.h
@@ -19,6 +19,77 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
   */
 
+/* Some notes on libpurple's object model.
+ *
+ * +---------------+
+ * | PurpleAccount | <-.
+ * +---------------+   |
+ * | gc            | --+--.
+ * .               .   |  |
+ * +---------------+   |  |
+ *                     |  |
+ *        .------------'  |
+ *        |               V
+ *        |     +------------------+             +----------------------+
+ *        |     | PurpleConnection |<--.     ,-->| MatrixConnectionData |
+ *        |     +------------------+   |     |   +----------------------+
+ *        +-----| account          |   `-----+---| pc                   |
+ *        |     | protocol_data    |---------'   .                      .
+ *        |     .                  .             +----------------------+
+ *        |     +------------------+
+ *        |
+ *        |     +--------------------+            +--------------------+
+ *        |     | PurpleConversation |<--.   ,--->| PurpleConvChat     |
+ *        |     +--------------------+   |   |    +--------------------+
+ *        +-----| account            |   `---+----| conv               |
+ *        |     | name               |       |    .                    .
+ *        |     | title              |       |    +--------------------+
+ *        |     | u.chat             |-------'
+ *        |     | data               |
+ *        |     .                    .
+ *        |     +--------------------+
+ *        |
+ *        |     +--------------------+
+ *        |     | PurpleBlistNode    |
+ *        |     +--------------------+
+ *        |     .                    .
+ *        |     +--------------------+
+ *        |               ^
+ *        |               | (inherits)
+ *        |     +--------------------+
+ *        |     | PurpleChat         |
+ *        |     +--------------------+
+ *        '-----| account            |
+ *              | components         |
+ *              .                    .
+ *              +--------------------+
+ *
+ *
+ *
+ * There is one PurpleAccount for each account the user has configured.
+ *
+ * Each PurpleAccount has at most one active connections. When the user enables
+ * the account, a PurpleConnection is made, and we attach a MatrixConnectionData
+ * to it - this is managed in matrix-connection.c. If there is an error on the
+ * connection, or the user explicitly disables the account, the PurpleConnection
+ * is deleted, and the MatrixConnectionData along with it.
+ *
+ * A PurpleChat (and a PurpleBuddy, but we don't have much to do with them)
+ * represents an entry on the buddylist. It has a hashtable called 'components'
+ * which stores the necessary information about the chat - in our case this is
+ * just the room id.
+ *
+ * A PurpleConversation represents an active conversation, and has a chat window
+ * associated with it. Its 'name' is not visible to the user; instead it is
+ * a unique id for the conversation - in our case the room id. Libpurple has
+ * some magic which looks up the 'name' against the 'components' of PurpleChats
+ * in the buddy list, and if a match is found, will set the title automatically.
+ *
+ * The PurpleConversation also has a hashtable which is used to track a range of
+ * protocol-specific data: see PURPLE_CONV_DATA_* in matrix-room.c for details
+ * of this.
+ */
+
 #ifndef LIBMATRIX_H
 #define LIBMATRIX_H