From 95dbb68b388dc4cf13491b9e04b197b17144f745 Mon Sep 17 00:00:00 2001
From: James Booth <boothj5@gmail.com>
Date: Tue, 22 May 2012 00:19:38 +0100
Subject: [PATCH] Added some code documentation, DESIGN

---
 DESIGN | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 DESIGN

diff --git a/DESIGN b/DESIGN
new file mode 100644
index 00000000..54194438
--- /dev/null
+++ b/DESIGN
@@ -0,0 +1,166 @@
+Responsibilities are generally seperated into modules.
+
+profanity.c
+===========
+
+Contains initialisation, main loop, and shutdown functions.
+
+Initialisation is loading preferences, initialising any libraries/files/data 
+structures used.
+
+The main loop is where the work is done.  It will keep checking for a new
+character on the input, if there is one deals with it, if not, goes around the
+loop again.
+
+If the character was a newline, the input line is processed, the result of
+processing profanity will either continue (TRUE) or stop (FALSE).
+
+Shutting down just involves clearing up resources.
+
+title_bar.c, windows.c, status_bar.c, input_win.c
+=================================================
+
+Represent the different windows in Ncurses.
+
+     ----------------------------------------------
+    |  TITLE_BAR                                   |
+     ----------------------------------------------
+    |                                              |
+    |                                              |
+    |  WINDOWS                                     |
+    |                                              |
+    |                                              |
+     ----------------------------------------------
+    |  STATUS_BAR                                  |
+     ----------------------------------------------
+    |  INPUT_WIN                                   |
+     ----------------------------------------------
+
+The interface to the UI is all through windows.h, all UI modules share this
+header:
+
+
+                            windows.h
+                                |
+                                |
+          --------------------------------------------------
+         |             |               |                    |
+    title_bar.c     windows.c       status_bar.c        inp_win.c
+
+
+
+So any calls to the UI are through windows.h
+
+title_bar.c and status_bar.c are pretty trivial.
+
+windows.c
+---------
+
+Contains a list of prof_win structs called _wins, which consist of:
+
+    from:  A string, the name of the recipient for this chat window
+    win:   An ncurses pad containing the chat
+    y_pos: The current position in the chat window
+    paged: Whether or not the pad has been paged (i.e not showing the end)
+
+The console is _wins[0], and has a special 'from' value of "_cons".
+
+This module contains things like a pointer to the console window, the index
+of the current window being displayed, a dirty flag that indicated the current
+windows should be updated next time around the loop.
+
+inp_win.c
+---------
+
+Doesn't do much more than handle each character with inp_get_char().  Deals
+with all special chars for editing the input, HOME, PAGE UP, UP, DOWN etc.
+
+command.c
+=========
+
+When the main input loop gets a '\n', process_input() is called with the 
+line of input.
+
+This is where each command/message is handled.
+
+jabber.c
+========
+
+All interaction with libstrophe is done here.  Contains a references to the
+libstrophe objects, connection, context etc.
+
+Functions ending 'handler' are callback handlers registered with libstrophe,
+for incomming messages etc.
+
+contact.c
+=========
+
+PContact represents a contact with:
+
+    name:   The contact full JID, e.g. somecontact@server.org
+    show:   "Online", "Away" etc
+    status: "I'm not here right now", "At lunch" etc
+
+It's an opaque pointer so all access to a PContact is encapsulated in this
+module.
+
+contact_list.c
+==============
+
+Currently has two purposes.
+
+Firstly stores a live list of online contacts.  Live meaning jabber.c will 
+call contact_list_add() and contact_list_remove() as it gets presence
+notifications.
+
+Secondly it is used for autocompleting contact names when typing them, hence
+it stores the contact in a PAutocomplete, described later.
+
+history.c
+=========
+
+Stores a history of all input and allows navigating through it, bash style.
+
+Uses PHistory object, described later.
+
+preferences.c
+=============
+
+Deals with loading and setting preferences saved in ~/.profanity.
+
+Also allows autocomplete of previous JIDs the use has logged in with 
+(stored in ~/.profanity) by storing them in a PAutocomplete.
+
+common.c
+========
+
+Functions written where older versions of GLib does not have them.
+
+util.c
+======
+
+Some util functions, should probably move to common.c.
+
+log.c
+=====
+
+Stored a reference to the log file, and provides functions for writing to it.
+
+Library like modules
+====================
+
+prof_history.c and prof_autocomplete.c implement a generic way to deal with 
+command history and command autocompletion respectively.
+
+The rest of Profanity uses them indirectly, via history.c for example.
+And they know nothing about Profanity (no includes).
+
+These modules use opaque pointers so all access must be through functions
+exposed in their headers.
+
+The idea is that these modules could be included in other applications.
+
+The "prof_" prefix is just because they were created whilst developing
+Profanity.
+
+