documenting classes!

3 files changed, 71 insertions, 35 deletions

diff --git a/src/openbox.cc b/src/openbox.cc
index 4aac9ba5..2d1b0307 100644
--- a/src/openbox.cc
+++ b/src/openbox.cc
@@ -44,22 +44,6 @@ namespace ob {
 Openbox *Openbox::instance = (Openbox *) 0;
 
 
-int Openbox::xerrorHandler(Display *d, XErrorEvent *e)
-{
-#ifdef DEBUG
-  char errtxt[128];
-
-  XGetErrorText(d, e->error_code, errtxt, 128);
-  printf("X Error: %s\n", errtxt);
-#else
-  (void)d;
-  (void)e;
-#endif
-
-  return false;
-}
-
-
 void Openbox::signalHandler(int signal)
 {
   switch (signal) {
@@ -86,7 +70,7 @@ Openbox::Openbox(int argc, char **argv)
 {
   struct sigaction action;
 
-  _state = State_Starting;
+  _state = State_Starting; // initializing everything
 
   Openbox::instance = this;
 
@@ -118,6 +102,8 @@ Openbox::Openbox(int argc, char **argv)
 
 Openbox::~Openbox()
 {
+  _state = State_Exiting; // time to kill everything
+  
   // close the X display
   otk::OBDisplay::destroy();
 }
@@ -209,7 +195,7 @@ void Openbox::showHelp()
 
 void Openbox::eventLoop()
 {
-  while (_state == State_Normal) {
+  while (!_doshutdown) {
     if (XPending(otk::OBDisplay::display)) {
       XEvent e;
       XNextEvent(otk::OBDisplay::display, &e);
diff --git a/src/openbox.hh b/src/openbox.hh
index 76a7d973..a479a45d 100644
--- a/src/openbox.hh
+++ b/src/openbox.hh
@@ -14,39 +14,74 @@ extern "C" {
 
 namespace ob {
 
+//! The main class for the Openbox window manager.
+/*!
+  Only a single instance of the Openbox class may be used in the application. A
+  pointer to this instance is held in the Openbox::instance static member
+  variable.
+  Instantiation of this class begins the window manager. After instantiation,
+  the Openbox::eventLoop function should be called. The eventLoop method does
+  not exit until the window manager is ready to be destroyed. Destruction of
+  the Openbox class instance will shutdown the window manager.
+*/
 class Openbox
 {
 public:
-  static Openbox *instance;  // there can only be ONE instance of this class in
-                             // the program, and it is held in here
-
-  typedef std::vector<otk::ScreenInfo> ScreenInfoList;
+  //! The single instance of the Openbox class for the application.
+  /*!
+    Since this variable is globally available in the application, the Openbox
+    class does not need to be passed around to any of the other classes.
+  */
+  static Openbox *instance;
 
+  //! The posible running states of the window manager
   enum RunState {
+    //! The window manager is starting up (being created)
     State_Starting,
+    //! The window manager is running in its normal state
     State_Normal,
+    //! The window manager is exiting (being destroyed)
     State_Exiting
   };
   
 private:
   // stuff that can be passed on the command line
-  std::string _rcfilepath;   // path to the config file to use/in use
-  std::string _menufilepath; // path to the menu file to use/in use
-  char *_displayreq;         // display requested by the user
-  char *_argv0;              // argv[0], how the program was called
+  //! Path to the config file to use/in use
+  /*!
+    Defaults to $(HOME)/.openbox/rc3
+  */
+  std::string _rcfilepath;
+  //! Path to the menu file to use/in use
+  /*!
+    Defaults to $(HOME)/.openbox/menu3
+  */
+  std::string _menufilepath;
+  //! The display requested by the user, or null to use the DISPLAY env var
+  char *_displayreq;
+  //! The value of argv[0], i.e. how this application was executed
+  char *_argv0;
 
-  otk::OBTimerQueueManager _timermanager; // manages timers, so that they fire
-                                          // when their time elapses
+  //! Manages all timers for the application
+  /*!
+    Use of the otk::OBTimerQueueManager::fire funtion in this object ensures
+    that all timers fire when their times elapse.
+  */
+  otk::OBTimerQueueManager _timermanager;
 
-  RunState _state;           // the state of the window manager
+  //! The running state of the window manager
+  RunState _state;
 
-  ScreenInfoList _screenInfoList; // info for all screens on the display
+  //! When set to true, the Openbox::eventLoop function will stop and return
+  bool _doshutdown;
 
+  //! Parses the command line used when executing this application
   void parseCommandLine(int argv, char **argv);
+  //! Displays the version string to stdout
   void showVersion();
+  //! Displays usage information and help to stdout
   void showHelp();
 
-  static int xerrorHandler(Display *d, XErrorEvent *e);
+  //! Handles signal events for the application
   static void signalHandler(int signal);
 
 public:
@@ -59,18 +94,33 @@ public:
   //! Openbox destructor.
   virtual ~Openbox();
 
-  //! Returns the state of the window manager (starting, exiting, etc).
+  //! Returns the state of the window manager (starting, exiting, etc)
   inline RunState state() const { return _state; }
 
+  //! Returns the otk::OBTimerQueueManager for the application
+  /*!
+    All otk::OBTimer objects used in the application should be made to use this
+    otk::OBTimerQueueManager.
+  */
   inline otk::OBTimerQueueManager *timerManager() { return &_timermanager; }
 
+  //! The main function of the Openbox class
+  /*!
+    This function should be called after instantiating the Openbox class.
+    Loops indefinately while handling all events in the application.
+    The Openbox::shutdown method will cause this function to exit.
+  */
   void eventLoop();
 
   // XXX: TEMPORARY!#!@%*!^#*!#!#!
   virtual void process_event(XEvent *) = 0;
 
-  //! Requests that the window manager exit.
-  inline void shutdown() { _state = State_Exiting; }
+  //! Requests that the window manager exit
+  /*!
+    Causes the Openbox::eventLoop function to stop looping, so that the window
+    manager can be destroyed.
+  */
+  inline void shutdown() { _doshutdown = true; }
 };
 
 }
diff --git a/src/workspace.cc b/src/workspace.cc
index 89134062..5259f3a5 100644
--- a/src/workspace.cc
+++ b/src/workspace.cc
@@ -413,7 +413,7 @@ bool Workspace::isCurrent(void) const {
 }
 
 
-bool Workspace::isLastWindow(const BlackboxWindow* const w) const {
+bool Workspace::isLastWindow(const BlackboxWindow *w) const {
   return (w == windowList.back());
 }