Cleanup and add documentation

1 files changed, 29 insertions, 0 deletions

diff --git a/src/Gtk.dcl b/src/Gtk.dcl
index 964d2a4..9728d3e 100644
--- a/src/Gtk.dcl
+++ b/src/Gtk.dcl
@@ -1,5 +1,34 @@
 definition module Gtk
 
+/**
+ * This library provides an application framework based on the Gtk+ 3 GUI
+ * toolkit. For information about the C library, see the documentation at
+ * https://developer.gnome.org/gtk3/stable/.
+ *
+ * For a low-level interface to Gtk, see `Gtk.Internal`. This module can be
+ * used without dependencies on the framework, which provides additional
+ * abstractions.
+ *
+ * The application framework is monadic; see `Gtk.State`. A typical application
+ * will consist of a setup function which populates the initial window and sets
+ * up signals for buttons, menu items, etc. The setup function is run with
+ * `runGtk` (`Gtk.State`), which then enters the Glib main loop to handle
+ * events. Signal handlers are Clean functions and may modify the monadic
+ * state.
+ *
+ * For an overview of the available GUI elements, see `Gtk.Widgets`. The
+ * relevant signals are provided in `Gtk.Signals`. Check the reference manual
+ * to see which signals are emitted for which types of widgets.
+ *
+ * NB: this library is not intended to be an exhaustive interface to Gtk. New
+ * functionality is added on a by-need basis. There is, however, enough example
+ * code available in these modules to be able to quickly add support for so far
+ * unsupported parts of Gtk.
+ *
+ * A simple share system, based on that of iTasks, is provided in `Gtk.Shares`
+ * and allows the programmer to easily keep shared data.
+ */
+
 import Gtk.Shares
 import Gtk.Signal
 import Gtk.State