# HG changeset patch
# User Jacob Dawid <jacob.dawid@googlemail.com>
# Date 1338638271 -7200
# Node ID 565ddd85565e39a979805eff1d269a779c458f5b
# Parent  5cb54cca8a0675f08c8b3dacc829f4d33e864112
Added comments for the octave-adapter module.

* octave-adapter/octave-link.h: Added comments.
* octave-adapter/octave-main-thread.h: Added comments.
* octave-adapter/symbol-information.h: Added comments.

diff -r 5cb54cca8a06 -r 565ddd85565e gui/src/octave-adapter/octave-link.h
--- a/gui/src/octave-adapter/octave-link.h	Fri Jun 01 23:54:14 2012 +0200
+++ b/gui/src/octave-adapter/octave-link.h	Sat Jun 02 13:57:51 2012 +0200
@@ -79,49 +79,87 @@
 
 /**
   * \class OctaveLink
-  * Manages a link to an octave instance.
+  * \brief Provides threadsafe access to octave.
+  * \author Jacob Dawid
+  * This class is a wrapper around octave and provides threadsafety by
+  * buffering access operations to octave and executing them in the readline
+  * even hook, which lives in the octave thread.
   */
-class octave_link:public QObject
+class octave_link : public QObject
 {
   Q_OBJECT
 public:
+  /** Provides a way to access the unique octave_link object. */
   static octave_link *
-  instance ()
-  {
-    return &_singleton;
-  }
+  instance () { return &_singleton; }
+
+  /** Starts octave. */
+  void launch_octave ();
 
-  void launch_octave ();
+  /** Attempts to close octave. */
   void terminate_octave ();
+
+  /** Returns the current history model. */
   QStringListModel *get_history_model ();
+
+  /** Returns the current workspace model. */
   workspace_model *get_workspace_model ();
 
+  /** Triggers an update of the history model. */
   void trigger_update_history_model ();
+
+  /** Updates the current working directory. */
   void update_current_working_directory ();
 
+  /** Acquires the symbol information. You need to acquire that before
+    * actually accessing it. Make sure that you release it properly in order
+    * to avoid deadlocks. */
   void acquire_symbol_information ();
+
+  /** Releases access to the symbol information. */
   void release_symbol_information ();
+
+  /** Update symbol information from octave's symboltable. */
   void build_symbol_information ();
+
+  /** Provides acces to the current symbol information.
+    * WARNING: Always acquire the symbol information before actually
+    * using it and make sure you release it properly afterwards.
+    */
   const QList <symbol_information>& get_symbol_information () const;
 
 signals:
+  /** Emitted, whenever the working directory of octave changed. */
   void working_directory_changed (QString directory);
 
 private:
+  /** Singleton. */
   octave_link ();
   ~octave_link ();
 
+  /** Stores the current history_model. */
   QStringListModel *_history_model;
+
+  /** Stores the current workspace model. */
   workspace_model *_workspace_model;
 
-  // Threads for running octave and managing the data interaction.
+  /** Thread running octave_main. */
   octave_main_thread *_octave_main_thread;
+
+  /** Timer for periodically updating the workspace model from the current
+    * symbol information. */
   QTimer _update_workspace_model_timer;
 
+  /** Semaphore to lock access to the symbol information. */
   QSemaphore *_symbol_information_semaphore;
+
+  /** Stores the current symbol information. */
   QList <symbol_information> _symbol_information;
 
+  /** Stores the last known current working directory of octave. */
   QString _current_working_directory;
+
+  /** Unique instance. Singelton! */
   static octave_link _singleton;
 };
 #endif // OCTAVELINK_H
diff -r 5cb54cca8a06 -r 565ddd85565e gui/src/octave-adapter/octave-main-thread.h
--- a/gui/src/octave-adapter/octave-main-thread.h	Fri Jun 01 23:54:14 2012 +0200
+++ b/gui/src/octave-adapter/octave-main-thread.h	Sat Jun 02 13:57:51 2012 +0200
@@ -19,16 +19,25 @@
 #define OCTAVEMAINTHREAD_H
 
 #include <QThread>
-class octave_main_thread:public QThread
+
+/**
+  * \class octave_main
+  * \brief This class represents a thread just running octave_main.
+  * \author Jacob Dawid
+  */
+class octave_main_thread : public QThread
 {
   Q_OBJECT
 public:
+  /** Creates a new thread running octave_main. */
   octave_main_thread (QObject * parent);
 
 signals:
+  /** This signal will be emitted when the thread is about to actually run octave_main. */
   void ready();
 
 protected:
+  /** Runs octave_main. */
   void run ();
 };
 
diff -r 5cb54cca8a06 -r 565ddd85565e gui/src/octave-adapter/symbol-information.h
--- a/gui/src/octave-adapter/symbol-information.h	Fri Jun 01 23:54:14 2012 +0200
+++ b/gui/src/octave-adapter/symbol-information.h	Sat Jun 02 13:57:51 2012 +0200
@@ -57,6 +57,15 @@
 #include "octave/utils.h"
 #include "octave/variables.h"
 
+/**
+  * \struct symbol_information
+  * \brief Meta-information over a symbol-table entry.
+  * \author Jacob Dawid
+  * This struct is used to store meta information over a symbol entry.
+  * It reduces memory consumption, since it only stores relevant data
+  * about a symbol-table entry that will be used in the model for the
+  * graphical user interface.
+  */
 typedef struct symbol_information
 {
   enum Scope
@@ -72,12 +81,14 @@
   QString _value;
   Scope   _scope;
 
+  /** Hashes the symbol information for quickly comparing it. */
   int
   hash () const
   {
     return qHash (_symbol) + qHash (_type) + qHash (_value) + (int)_scope;
   }
 
+  /** Compares two symbol information objects. */
   bool
   equals (const symbol_information& other) const
   {
@@ -90,6 +101,7 @@
       }
   }
 
+  /** Extracts meta information from a given symbol record. */
   bool
   from_symbol_record (const symbol_table::symbol_record& symbol_record)
   {
@@ -133,6 +145,4 @@
   }
 } symbol_information;
 
-
-
 #endif // SYMBOLINFORMATION_H