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/State.dcl | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

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

diff --git a/src/Gtk/State.dcl b/src/Gtk/State.dcl
index c4e17a2..1dde9d1 100644
--- a/src/Gtk/State.dcl
+++ b/src/Gtk/State.dcl
@@ -1,5 +1,10 @@
 definition module Gtk.State
 
+/**
+ * This module provides types and functions to set up the monadic state of a
+ * Gtk program and run an application.
+ */
+
 from StdMaybe import :: Maybe
 
 from Control.Applicative import class pure, class <*>, class Applicative
@@ -10,6 +15,10 @@ from Data.Map import :: Map
 from Gtk.Shares import :: ShareId
 from Gtk.Signal import :: SignalHandlerInternal
 
+/**
+ * In the internal state of the `GtkM` monad. It is exported for use in other
+ * modules of the Gtk library; it should not normally be used by applications.
+ */
 :: GtkState =
 	{ world           :: !()
 	, return          :: !Bool
@@ -17,9 +26,10 @@ from Gtk.Signal import :: SignalHandlerInternal
 	, signal_counter  :: !Int
 	, timeouts        :: !Map Int (GtkM Bool)
 	, timeout_counter :: !Int
-	, shares          :: !Map ShareId Dynamic // TODO: make this map strict to be able to free references in it
+	, shares          :: !Map ShareId Dynamic
 	}
 
+//* The Gtk state monad.
 :: GtkM a =: GtkM (GtkState -> (a, GtkState))
 
 instance Functor GtkM
@@ -27,18 +37,50 @@ instance pure GtkM
 instance <*> GtkM
 instance Monad GtkM
 
+//* A new, empty state.
 newGtkState :: GtkState
 
+//* Run a Gtk monad in a new, empty state.
 runGtk :: !(GtkM a) !*World -> (!a, !*World)
 
+//* Get the internal state.
 getState :: GtkM GtkState
+//* Modify the internal state.
 modState :: !(GtkState -> GtkState) -> GtkM GtkState
 
+/**
+ * Run a function in the `GtkM` monad and discard its result. This function is
+ * typically used with functions from `Gtk.Internal` and is not normally used
+ * directly.
+ */
 toState :: !(A.a: a -> a) -> GtkM ()
+
+/**
+ * Run a function in the `GtkM` monad and return its result. This function is
+ * typically used with functions from `Gtk.Internal` and is not normally used
+ * directly.
+ */
 toStateR :: !(A.a: a -> (r,a)) -> GtkM r
 
+//* Apply a function with side effects in the `GtkM` monad.
 appWorld :: !(*World -> *World) -> GtkM ()
+//* Apply a function with side effects in the `GtkM` monad; return its result.
 accWorld :: !(*World -> (r,*World)) -> GtkM r
 
+/**
+ * Request graceful termination of the program. This sets the `return` field
+ * of the `GtkState`, after which `runGtk` will terminate before the next
+ * iteration.
+ */
 quit :: GtkM ()
+
+/**
+ * Run the Glib main loop as long as there are events pending. This may be
+ * useful before starting a long blocking operation in Clean, such that all
+ * updates to the views have been applied. You can thus set text in a status
+ * bar or show a spinner before the blocking operation starts.
+ *
+ * Unfortunately, threading or Glib's background task mechanism is not
+ * implemented, so the blocking operation will still freeze the GUI.
+ */
 runWhileEventsPending :: GtkM ()
-- 
cgit v1.2.3