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/Shares.dcl | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

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

diff --git a/src/Gtk/Shares.dcl b/src/Gtk/Shares.dcl
index d1e5556..48db8eb 100644
--- a/src/Gtk/Shares.dcl
+++ b/src/Gtk/Shares.dcl
@@ -1,20 +1,35 @@
 definition module Gtk.Shares
 
+/**
+ * This module provides shares in the `GtkM` monad, allowing the programmer to
+ * abstract from global state. They are loosely based on SDSs in iTasks, but
+ * much less advanced.
+ */
+
 from Gtk.State import :: GtkM
 
+//* Identifier of a share.
 :: ShareId :== String
 
-//* Exported to have a TC instance -- do not use directly!
+//* Exported to have a TC instance --- do not use directly!
 :: Shared a :== (String,a)
 
+//* Types must instantiate this class to be able to be shared.
 class shared a | TC a
 
+//* Sets up a share with a default value (cf. iTasks' `sharedStore`).
 share :: !ShareId a -> Shared a | shared a
 
 getShared :: !(Shared a) -> GtkM a | shared a
 setShared :: !(Shared a) !a -> GtkM a | shared a
 updateShared :: !(a -> a) !(Shared a) -> GtkM a | shared a
 
+/**
+ * A share with an initialization function. It will always return the same
+ * value, namely the result of the initialization function, but that function
+ * will only be evaluated once. It can be seen as an impure CAF.
+ */
 singletonShared :: !String !(GtkM a) -> GtkM a | shared a
 
+//* Evaluate a function with a temporary share.
 withShared :: a !((Shared a) -> GtkM b) -> GtkM b | shared a
-- 
cgit v1.2.3