From 0497dfb79211aa1e64304fa446d230c41ca73daa Mon Sep 17 00:00:00 2001
From: Camil Staps
Date: Fri, 1 Nov 2019 18:41:10 +0100
Subject: Cleanup and add documentation

---
 src/Gtk/Signal.dcl | 57 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 48 insertions(+), 9 deletions(-)

(limited to 'src/Gtk/Signal.dcl')

diff --git a/src/Gtk/Signal.dcl b/src/Gtk/Signal.dcl
index fa9babf..85a780c 100644
--- a/src/Gtk/Signal.dcl
+++ b/src/Gtk/Signal.dcl
@@ -1,5 +1,9 @@
 definition module Gtk.Signal
 
+/**
+ * This module provides functionality for Gtk signals.
+ */
+
 from System._Pointer import :: Pointer
 
 from Gdk.Events import :: GdkEvent
@@ -8,13 +12,19 @@ from Gtk.Tune import class tune
 from Gtk.Types import :: GtkPropagate, :: GtkTimeout
 from Gtk.Widgets import class gtkWidget
 
+/**
+ * If more handlers are defined outside this module (and hence outside the
+ * `GSignalHandler` type), they must instantiate this class to be able to be
+ * installed on widgets.
+ */
 class signalHandler h
 where
+	//* The name of the signal, e.g. `destroy` or `key-press-event`.
 	signalName :: !h -> String
+	//* An internal representation of the handler.
 	signalHandler :: !h -> SignalHandlerInternal
 
-:: SignalHandler = E.h: SignalHandler h & signalHandler h
-
+//* A number of basic signals. See the Gtk documentation for their usage.
 :: GSignalHandler
 	= ActivateHandler      !(GtkM ())
 	| ChangedHandler       !(GtkM ())
@@ -29,28 +39,57 @@ where
 
 instance signalHandler GSignalHandler
 
+/**
+ * Inner representation of the various types of signal handlers that there are.
+ * This is only needed outside this module when adding more signals.
+ */
 :: SignalHandlerInternal
 	= SHI_Void !(GtkM ())
 	| SHI_Pointer_Bool !(Pointer -> GtkM Bool)
 	| SHI_Int_Int_Bool !(Int Int -> GtkM Bool)
 	| SHI_Int_Int_Pointer_Pointer_Bool !(Int Int Pointer Pointer -> GtkM Bool)
 
+/**
+ * Install a signal handler on a widget. Often, the `tune` instance defined
+ * below leads to more readable code.
+ */
 installSignalHandler :: !h !w -> GtkM w | signalHandler h & gtkWidget w
 
-instance tune w SignalHandler | gtkWidget w
+//* Alternative for `installSignalHandler` for more readable code.
 instance tune w GSignalHandler | gtkWidget w
 
-saveState :: GtkM ()
-retrieveState :: GtkM GtkState
+/**
+ * Run a function at a certain interval. The function will continue to run
+ * until it returns `False`. Note that Glib timeouts cannot be used for precise
+ * timing; see the documentation for more details:
+ * https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-timeout-add
+ */
+addTimeout :: !GtkTimeout !(GtkM Bool) -> GtkM ()
 
-//* Wrap functionality in `saveState` and `retrieveState` if it can be re-entrant.
+/**
+ * Wrap functionality with `saveState` and `retrieveState`. This is needed if
+ * it can be re-entrant, for example when it can trigger signals. See the
+ * documentation on `saveState` for more details.
+ */
 withPossibleCallback :: !(GtkM a) -> GtkM a
 
-// Only for foreign export:
+/**
+ * Some functions can lead to Gtk signals to be emitted. If these signals have
+ * handlers set up, the function is re-entrant (may return to Clean code). For
+ * this kind of functions, we need to save the `GtkM` state beforehand and
+ * retrieve it afterwards, because the signal handler may rely on that state
+ * and may modify it. `saveState` saves the state internally; `retrieveState`
+ * restores it. `withPossibleCallback` is a convenient wrapper combining both.
+ */
+saveState :: GtkM ()
+
+//* Retrieve the state saved with `saveState`.
+retrieveState :: GtkM GtkState
+
+// The functions below are only exported because they need a foreign export entry point:
 handleSignal_void :: !Pointer !Int -> Int
 handleSignal_pointer_bool :: !Pointer !Pointer !Int -> Int
 handleSignal_int_int_bool :: !Pointer !Int !Int !Int -> Int
 handleSignal_int_int_pointer_pointer_bool :: !Pointer !Int !Int !Pointer !Pointer !Int -> Int
 
-addTimeout :: !GtkTimeout !(GtkM Bool) -> GtkM ()
-handleTimeout :: !Int -> Int // only for foreign export
+handleTimeout :: !Int -> Int
-- 
cgit v1.2.3