Some documentation in the code...

src/ipcmsg.cpp

@@ -27,9 +27,12 @@
  *
  ********************************************************************
  *
- * File: 
+ * File: ipcmsg.cpp
  * 
  * Purpose:
+ * Define the initialization methods for message istances.
+ * Those messages are used to make different plugins and core
+ * communicate using signals/slots QT method.
  *
  */
 
@@ -40,6 +43,7 @@
 #include "ipcmsg.h"
 #include "pluginsinterfaces.h"
 
+
 SKMessage::SKMessage(QString s, QString h, QHash<QString, QString > p)
 {
    handle=h;
@@ -91,6 +95,12 @@ SKMessage::SKMessage(const SKMessage &other)
    time=other.time;
 }
 
+/*
+ * This is a special case initialization where
+ * we have to pass a WebView derived object
+ * between a mainwindow and a subwindow
+ * using QT WebKit
+ */
 SKMessage::SKMessage(QString h, SkylivexWin* win)
 {
    sender= QString("unknown");

src/ipcmsg.h

@@ -27,9 +27,14 @@
  *
  ********************************************************************
  *
- * File: 
+ * File: ipcmsg.h
  * 
- * Purpose:
+ * Purpose: 
+ * Define an object rapresenting a message
+ * that can be used to make plugins and core communicate
+ * even between different threads
+ *
+ * They will be passed using signal/slot mechanism in QT,
  *
  */
 
@@ -46,8 +51,9 @@ class SkylivexWin;
 
 /*
  * SKMessage
- * An object representing an IPC message
- * between threads
+ * An object representing an IPC message,
+ * both thread to thread (plugins) and between
+ * thread and core
  */
 class SKMessage
 {
@@ -57,11 +63,11 @@ class SKMessage
       SKMessage(const SKMessage &other);
       ~SKMessage();
 
-      QTime time;
-      QString sender;
-      QString handle;
-      SkylivexWin* webwin;
-      QHash<QString, QString > parameters;
+      QTime time;                    // A timestamp, just in case
+      QString sender;                // the name of the sender component
+      QString handle;                // the message type
+      SkylivexWin* webwin;           // sometime we need to transport a qobject representing a WebView
+      QHash<QString, QString > parameters; // mixed parameters in form of hash
 
       SKMessage(QString s, QString h, QHash<QString, QString > p);
       SKMessage(QString h, QHash<QString, QString > p);

src/jsbridge.cpp

@@ -27,9 +27,11 @@
  *
  ********************************************************************
  *
- * File: splashpage.cpp 
+ * File: jsbridge.cpp 
  * 
  * Purpose:
+ * Define an interface between javascript in the 
+ * Webkit based gui and the c++ based core of the application
  *
  */
 #include <QString>
@@ -39,11 +41,38 @@
 #include "jsbridge.h"
 
 
+/*
+ * Method: changePageContent
+ *
+ * Arguments:
+ *   - Qstring elementid: a string with an element id in the html
+ *   - QString content: this will be the .innerHTML content of the
+ *                      element we want to change
+ *
+ * This method give our core a way to change directly the content
+ * of an HTML node by a javascript call like
+ * document.getElementById(elementid).innerHTML=content;
+ * in javascript
+ */
 void JSBridge::changePageContent(QString elementid, QString content)
 {
    emit changeContent(elementid, content);
 }
 
+
+/*
+ * Method: pushLogin
+ *
+ * Arguments: 
+ *   - Qstring username: the username passed to the login form
+ *   - QString password: the password passed to the login form
+ *
+ * This method is to be called on the javascript side
+ * to communicate to the core the login info compiled
+ * by the user on the login form
+ *
+ * It will push an IPC message to the core and other plugins
+ */
 void JSBridge::pushLogin(QString username, QString password)
 {
    std::cout << "pushLogin called from JS"  << std::endl;
@@ -53,29 +82,77 @@ void JSBridge::pushLogin(QString username, QString password)
    wwin->sendMessage(loginmsg);
 }
 
+/*
+ * Method: resizeWin
+ *
+ * Arguments:
+ *   - int width: an integer for the window width
+ *   - int height: an integer for the window height
+ *
+ * This method is to be called from the javascript
+ * side to make the GUI window resize to the desidered size
+ */
 void JSBridge::resizeWin(int width, int height)
 {
    std::cout << "resizeWin called from JS"  << std::endl;
    wwin->resize(width, height);
 }
 
+/*
+ * Method: toggleBorders
+ *
+ * Arguments: 
+ *   - bool borders: a boolean value defining if we want decorators on 
+ *                   the gui window
+ *
+ * With this method we give javascript a way to enable or disable window
+ * decorators
+ */
 void JSBridge::toggleBorders(bool borders)
 {
    wwin->toggleBorders(borders);
 }
 
+/*
+ * Method: toggleTransparentBackground
+ *
+ * Arguments: 
+ *   - bool transparentbg: a boolean value defining if we want
+ *                         the GUI window have a transparent
+ *                         background
+ *
+ * This method give the javascript side a way to toggle the
+ * background of the window transparent or not
+ */
 void JSBridge::toggleTransparentBackground(bool transparentbg)
 {
    wwin->toggleTransparentBackground(transparentbg);
 }
 
-/* a private message */
+/*
+ * Method: chat_message_send
+ *
+ * Arguments:
+ *   - QString dest: the username destination of the chat message
+ *   - Qstring message: the private chat message
+ *
+ * This method is to be called from javascript to send a private
+ * message in chat to a specified user
+ */
 void JSBridge::chat_message_send(QString dest, QString message)
 {
 
 }
 
-/* a public message */
+/*
+ * Method: chat_message_send
+ *
+ * Arguments:
+ *   - QString message: the chat message to be sent
+ *
+ * This method is to be called from the javascript
+ * to send a public message on chat, on the active channel/telescope
+ */
 void JSBridge::chat_message_send(QString message)
 {
    std::cout << "public message send called from JS"  << std::endl;
@@ -84,6 +161,15 @@ void JSBridge::chat_message_send(QString message)
    wwin->sendMessage(chatmsg);
 }
 
+/*
+ * Method: change_telescope
+ *
+ * Arguments:
+ *   - QString tele: the name of the telescope we ask to change to
+ *
+ * This method, called from the javascript side, permit to change
+ * the active telescope
+ */
 void JSBridge::change_telescope(QString tele)
 {
    std::cout << "Telescope change requested from JS" << std::endl;
@@ -93,6 +179,22 @@ void JSBridge::change_telescope(QString tele)
 
 }
 
+/*
+ * Method: open_window
+ *
+ * Arguments:
+ *   - Qstring url: this contain the URL to be opened in new window
+ *   - bool Modal: if true, the new window is modal
+ *
+ * This method, called from the javascript side, permit
+ * to open a new window to an URL (local or remote) that
+ * will have the JSBridge accessible.
+ *
+ * This needs to be used carefully and only on strictly trusted
+ * URL ( better if only on local one! ), cause make
+ * an untrusted site the permission to access to our core
+ * by using the JSBridge object can be (IS!) a security issue.
+ */
 SkylivexWin* JSBridge::open_window(QString url, bool Modal)
 {
    if(Modal)

src/jsbridge.h

@@ -27,9 +27,12 @@
  *
  ********************************************************************
  *
- * File: 
+ * File: jsbridge.h
  * 
  * Purpose:
+ * Define a QObject used to export to javascript
+ * some methods to make the webkit based GUI communicate
+ * with the core.
  *
  */
 #ifndef JSBRIDGE_H