diff --git a/src/common/guifacade.cpp b/src/common/guifacade.cpp
index b28c65130..e786dba40 100644
--- a/src/common/guifacade.cpp
+++ b/src/common/guifacade.cpp
@@ -48,6 +48,7 @@ namespace gui {
   
   
   
+  /** load and start the GUI as a plugin */
   struct GuiRunner
     : public GuiFacade
     {
@@ -78,7 +79,7 @@ namespace gui {
   
   
   
-  namespace { // implementation details : start GUI through GuiStarterPlugin
+  namespace { // implementation of GUI-"Subsystem" : start GUI through GuiStarterPlugin
     
     scoped_ptr<GuiRunner> facade (0);
     
diff --git a/src/gui/guifacade.hpp b/src/gui/guifacade.hpp
index 212a62b47..d7bf7f542 100644
--- a/src/gui/guifacade.hpp
+++ b/src/gui/guifacade.hpp
@@ -60,11 +60,16 @@ namespace gui {
    * When running Lumiera with a GUI is required (the default case),
    * it is loaded as dynamic module, thus defining the interface(s) 
    * for any further access. After successfully loading and starting
-   * the GUI, this gui::Facade is wired internally with this interface
-   * such as to allow transparent access from within the core. This
-   * startup sequence includes providing the GUI with similar facade
-   * access via interface handles for communication with Backend and
-   * Proc-Layer.
+   * the GUI, the actual "business" interfaces of the GUI are opened
+   * and wired internally such as to allow transparent access from
+   * within the core.
+   * 
+   * \par implementation notes
+   * This is an facade interface to the GUI subsystem, but it is setup
+   * somewhat special, as its sole purpose is to expose the subsystem
+   * descriptor, which, when started, loads the GUI as a plugin and
+   * invokes \c kickOff(term) there. For the implementation see
+   * gui::GuiRunner (guifacade.cpp) and guistart.cpp (the plugin).
    * 
    * @note this facade is intended to be used by Lumiera main solely.
    *       client code should always use the "business" interface(s).
diff --git a/src/include/guinotification-facade.h b/src/include/guinotification-facade.h
index aba81ea0b..ea575fb5f 100644
--- a/src/include/guinotification-facade.h
+++ b/src/include/guinotification-facade.h
@@ -26,6 +26,7 @@
  ** usable by scripts or the two lower layers. The main purpose of these services
  ** is to push informations and status updates into the GUI.
  **
+ ** @see notification-service.hpp implementation
  ** @see gui::GuiFacade
  ** @see main.cpp
  */