[Gtk2hs-commit] gtk2hs/gtk/Graphics/UI/Gtk/Display AccelLabel.chs,1.3,1.4 Image.chs.pp,1.4,1.5 Label.chs,1.5,1.6 ProgressBar.chs,1.5,1.6 Statusbar.chs,1.3,1.4

[Duncan C. <dun...@us...>]

Update of /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5160/gtk/Graphics/UI/Gtk/Display

Modified Files:
	AccelLabel.chs Image.chs.pp Label.chs ProgressBar.chs 
	Statusbar.chs 
Log Message:
Documentation changes and code formatting changes.


Index: Image.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Image.chs.pp,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- Image.chs.pp	25 Feb 2005 01:11:32 -0000	1.4
+++ Image.chs.pp	15 Mar 2005 19:59:09 -0000	1.5
@@ -126,42 +126,73 @@
 --------------------
 -- Constructors
 
--- | Create an image by loading a file.
+-- | Creates a new 'Image' displaying the file @filename@. If the file isn't
+-- found or can't be loaded, the resulting 'Image' will display a \"broken
+-- image\" icon.
+--
+-- If the file contains an animation, the image will contain an animation.
+--
+-- If you need to detect failures to load the file, use 'pixbufNewFromFile'
+-- to load the file yourself, then create the 'Image' from the pixbuf. (Or for
+-- animations, use 'pixbufAnimationNewFromFile').
+--
+-- The storage type ('imageGetStorageType') of the returned image is not
+-- defined, it will be whatever is appropriate for displaying the file.
 --
 imageNewFromFile :: FilePath -> IO Image
-imageNewFromFile path = makeNewObject mkImage $ liftM castPtr $ 
+imageNewFromFile filename =
+  makeNewObject mkImage $ liftM castPtr $
+  withUTFString filename $ \filenamePtr ->
 #if defined (WIN32) && GTK_CHECK_VERSION(2,6,0)
-  withUTFString path {#call unsafe image_new_from_file_utf8#}
+  {# call unsafe gtk_image_new_from_file_utf8 #}
 #else
-  withUTFString path {#call unsafe image_new_from_file#}
+  {# call unsafe gtk_image_new_from_file #}
 #endif
+    filenamePtr
 
--- | Create an 'Image' from a 
--- 'Pixbuf'.
+-- | Creates a new 'Image' displaying a 'Pixbuf'.
+--
+-- Note that this function just creates an 'Image' from the pixbuf. The
+-- 'Image' created will not react to state changes. Should you want that, you
+-- should use 'imageNewFromIconSet'.
 --
 imageNewFromPixbuf :: Pixbuf -> IO Image
-imageNewFromPixbuf pbuf = makeNewObject mkImage $ liftM castPtr $
-  {#call unsafe image_new_from_pixbuf#} pbuf
+imageNewFromPixbuf pixbuf =
+  makeNewObject mkImage $ liftM castPtr $
+  {# call unsafe image_new_from_pixbuf #}
+    pixbuf
 
--- | Create a set of images by specifying a stock
--- object.
+-- | Creates a 'Image' displaying a stock icon. If the stock icon name isn't
+-- known, a \"broken image\" icon will be displayed instead.
 --
-imageNewFromStock :: String -> IconSize -> IO Image
-imageNewFromStock stock ic = withUTFString stock $ \strPtr -> 
-  makeNewObject mkImage $ liftM castPtr $ {#call unsafe image_new_from_stock#}
-  strPtr (fromIntegral ic)
+imageNewFromStock :: 
+    String   -- ^ @stockId@ - a stock icon name
+ -> IconSize -- ^ @size@ - a stock icon size
+ -> IO Image
+imageNewFromStock stockId size =
+  makeNewObject mkImage $ liftM castPtr $
+  withUTFString stockId $ \stockIdPtr ->
+  {# call unsafe image_new_from_stock #}
+    stockIdPtr
+    (fromIntegral size)
 
 --------------------
 -- Methods
 
--- | Extract the Pixbuf from the 'Image'.
+-- | Gets the 'Pixbuf' being displayed by the 'Image'. The storage type of the
+-- image must be 'ImageEmpty' or 'ImagePixbuf' (see 'imageGetStorageType').
 --
 imageGetPixbuf :: Image -> IO Pixbuf
-imageGetPixbuf img = makeNewGObject mkPixbuf $ liftM castPtr $
+imageGetPixbuf self =
+  makeNewGObject mkPixbuf $ liftM castPtr $
   throwIfNull "Image.imageGetPixbuf: The image contains no Pixbuf object." $
-  {#call unsafe image_get_pixbuf#} img
+  {# call unsafe image_get_pixbuf #}
+    self
 
 -- | Overwrite the current content of the 'Image' with a new 'Pixbuf'.
 --
 imageSetFromPixbuf :: Image -> Pixbuf -> IO ()
-imageSetFromPixbuf img pb = {#call unsafe gtk_image_set_from_pixbuf#} img pb
+imageSetFromPixbuf self pixbuf =
+  {# call unsafe gtk_image_set_from_pixbuf #}
+    self
+    pixbuf

Index: ProgressBar.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/ProgressBar.chs,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- ProgressBar.chs	13 Mar 2005 19:34:32 -0000	1.5
+++ ProgressBar.chs	15 Mar 2005 19:59:10 -0000	1.6
@@ -24,10 +24,10 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- A widget which indicates progress visually.
+-- A widget which indicates progress visually
 --
 module Graphics.UI.Gtk.Display.ProgressBar (
--- * Description
+-- * Detail
 -- 
 -- | The 'ProgressBar' is typically used to display the progress of a long
 -- running operation. It provides a visual clue that processing is underway.
@@ -106,89 +106,102 @@
 -- | Creates a new 'ProgressBar'.
 --
 progressBarNew :: IO ProgressBar
-progressBarNew  = makeNewObject mkProgressBar $ liftM castPtr $
-  {#call unsafe progress_bar_new#}
+progressBarNew =
+  makeNewObject mkProgressBar $ liftM castPtr $
+  {# call unsafe progress_bar_new #}
 
 --------------------
 -- Methods
 
--- | Indicates that some progress is made, but you
--- don't know how much. Causes the progress bar to enter \`activity mode',
--- where a block bounces back and forth. Each call to
--- 'progressBarPulse' causes the block to move on by a little bit
--- (the amount of movement per pulse is determined by
+-- | Indicates that some progress is made, but you don't know how much. Causes
+-- the progress bar to enter \"activity mode\", where a block bounces back and
+-- forth. Each call to 'progressBarPulse' causes the block to move by a little
+-- bit (the amount of movement per pulse is determined by
 -- 'progressBarSetPulseStep').
 --
-progressBarPulse :: ProgressBarClass pb => pb -> IO ()
-progressBarPulse pb = {#call unsafe progress_bar_pulse#} (toProgressBar pb)
+progressBarPulse :: ProgressBarClass self => self -> IO ()
+progressBarPulse self =
+  {# call unsafe progress_bar_pulse #}
+    (toProgressBar self)
 
--- | Causes the given @text@ to appear
--- superimposed on the progress bar.
+-- | Causes the given @text@ to appear superimposed on the progress bar.
 --
-progressBarSetText :: ProgressBarClass pb => pb -> String -> IO ()
-progressBarSetText pb text = withUTFString text $
-  {#call unsafe progress_bar_set_text#} (toProgressBar pb)
+progressBarSetText :: ProgressBarClass self => self -> String -> IO ()
+progressBarSetText self text =
+  withUTFString text $ \textPtr ->
+  {# call unsafe progress_bar_set_text #}
+    (toProgressBar self)
+    textPtr
 
--- | Causes the progress bar to \`fill in' the
--- given fraction of the bar. The fraction should be between 0.0 and 1.0,
--- inclusive.
+-- | Causes the progress bar to \"fill in\" the given fraction of the bar. The
+-- fraction should be between 0.0 and 1.0, inclusive.
 --
-progressBarSetFraction :: ProgressBarClass pb => pb -> Double -> IO ()
-progressBarSetFraction pb fraction = {#call unsafe progress_bar_set_fraction#}
-  (toProgressBar pb) (realToFrac fraction)
+progressBarSetFraction :: ProgressBarClass self => self
+ -> Double -- ^ @fraction@ - fraction of the task that's been completed
+ -> IO ()
+progressBarSetFraction self fraction =
+  {# call unsafe progress_bar_set_fraction #}
+    (toProgressBar self)
+    (realToFrac fraction)
 
--- | Sets the fraction of total progress bar
--- length to move the bouncing block for each call to progressBarPulse.
---
--- * The @fraction@ parameter must be between 0.0 and 1.0.
+-- | Sets the fraction of total progress bar length to move the bouncing block
+-- for each call to 'progressBarPulse'.
 --
-progressBarSetPulseStep :: ProgressBarClass pb => pb -> Double -> IO ()
-progressBarSetPulseStep pb fraction = 
-  {#call unsafe progress_bar_set_pulse_step#} (toProgressBar pb) 
-  (realToFrac fraction)
+progressBarSetPulseStep :: ProgressBarClass self => self
+ -> Double -- ^ @fraction@ - fraction between 0.0 and 1.0
+ -> IO ()
+progressBarSetPulseStep self fraction =
+  {# call unsafe progress_bar_set_pulse_step #}
+    (toProgressBar self)
+    (realToFrac fraction)
 
--- | Returns the current fraction of the task
--- that has been completed.
+-- | Returns the current fraction of the task that's been completed.
 --
-progressBarGetFraction :: ProgressBarClass pb => pb -> IO Double
-progressBarGetFraction pb = liftM realToFrac $ 
-  {#call unsafe progress_bar_get_fraction#} (toProgressBar pb)
+progressBarGetFraction :: ProgressBarClass self => self
+ -> IO Double -- ^ returns a fraction from 0.0 to 1.0
+progressBarGetFraction self =
+  liftM realToFrac $
+  {# call unsafe progress_bar_get_fraction #}
+    (toProgressBar self)
 
--- | Returns the current pulseStep of the task
--- that has been completed.
+-- | Retrieves the pulse step set with 'progressBarSetPulseStep'
 --
-progressBarGetPulseStep :: ProgressBarClass pb => pb -> IO Double
-progressBarGetPulseStep pb = liftM realToFrac $ 
-  {#call unsafe progress_bar_get_pulse_step#} (toProgressBar pb)
-
+progressBarGetPulseStep :: ProgressBarClass self => self
+ -> IO Double -- ^ returns a fraction from 0.0 to 1.0
+progressBarGetPulseStep self =
+  liftM realToFrac $
+  {# call unsafe progress_bar_get_pulse_step #}
+    (toProgressBar self)
 
--- | Retrieve the text displayed superimposed on the
--- ProgressBar.
---
--- * Returns Nothing if no text was set.
+-- | Retrieves the text displayed superimposed on the progress bar, if any,
+-- otherwise @Nothing@.
 --
-progressBarGetText :: ProgressBarClass pb => pb -> IO (Maybe String)
-progressBarGetText pb = do
-  strPtr <- {#call unsafe progress_bar_get_text#} (toProgressBar pb)
-  if strPtr==nullPtr then return Nothing else liftM Just $ peekUTFString strPtr
+progressBarGetText :: ProgressBarClass self => self
+ -> IO (Maybe String) -- ^ returns text, or @Nothing@
+progressBarGetText self =
+  {# call unsafe progress_bar_get_text #}
+    (toProgressBar self)
+  >>= maybePeek peekUTFString
 
--- | Causes the progress bar to switch to a
--- different orientation (left-to-right, right-to-left, top-to-bottom, or
--- bottom-to-top).
+-- | Causes the progress bar to switch to a different orientation
+-- (left-to-right, right-to-left, top-to-bottom, or bottom-to-top).
 --
-progressBarSetOrientation :: ProgressBarClass pb => pb ->
-                             ProgressBarOrientation -> IO ()
-progressBarSetOrientation pb orientation = 
-  {#call progress_bar_set_orientation#} (toProgressBar pb)
-  ((fromIntegral.fromEnum) orientation)
+progressBarSetOrientation :: ProgressBarClass self => self
+ -> ProgressBarOrientation
+ -> IO ()
+progressBarSetOrientation self orientation =
+  {# call progress_bar_set_orientation #}
+    (toProgressBar self)
+    ((fromIntegral . fromEnum) orientation)
 
--- | Retrieve the current ProgressBar
--- orientation.
+-- | Retrieves the current progress bar orientation.
 --
-progressBarGetOrientation :: ProgressBarClass pb => pb ->
-                             IO ProgressBarOrientation
-progressBarGetOrientation pb = liftM (toEnum.fromIntegral) $
-  {#call unsafe progress_bar_get_orientation#} (toProgressBar pb)
+progressBarGetOrientation :: ProgressBarClass self => self
+ -> IO ProgressBarOrientation
+progressBarGetOrientation self =
+  liftM (toEnum . fromIntegral) $
+  {# call unsafe progress_bar_get_orientation #}
+    (toProgressBar self)
 
 --------------------
 -- Properties

Index: Statusbar.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Statusbar.chs,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Statusbar.chs	25 Feb 2005 01:11:32 -0000	1.3
+++ Statusbar.chs	15 Mar 2005 19:59:10 -0000	1.4
@@ -1,5 +1,5 @@
 -- -*-haskell-*-
---  GIMP Toolkit (GTK) Widget StatusBar
+--  GIMP Toolkit (GTK) Widget Statusbar
 --
 --  Author : Axel Simon
 --
@@ -24,10 +24,10 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- Report messages of minor importance to the user.
+-- Report messages of minor importance to the user
 --
 module Graphics.UI.Gtk.Display.Statusbar (
--- * Description
+-- * Detail
 -- 
 -- | A 'Statusbar' is usually placed along the bottom of an application's main
 -- 'Window'. It may provide a regular commentary of the application's status
@@ -103,76 +103,107 @@
 --------------------
 -- Constructors
 
--- | Create a new Statusbar.
+-- | Creates a new 'Statusbar' ready for messages.
 --
 statusbarNew :: IO Statusbar
-statusbarNew  = makeNewObject mkStatusbar $ 
-  liftM castPtr {#call unsafe statusbar_new#}
+statusbarNew =
+  makeNewObject mkStatusbar $ liftM castPtr $
+  {# call unsafe statusbar_new #}
 
 --------------------
 -- Methods
 
 type ContextId = {#type guint#}
 
--- | Given a context description, this function
--- returns a ContextId. This id can be used to later remove entries form the
--- Statusbar.
+-- | Returns a new context identifier, given a description of the actual
+-- context. This id can be used to later remove entries form the Statusbar.
 --
-statusbarGetContextId :: StatusbarClass sb => sb -> String -> IO ContextId
-statusbarGetContextId sb description = withUTFString description $
-  {#call unsafe statusbar_get_context_id#} (toStatusbar sb)
-
+statusbarGetContextId :: StatusbarClass self => self
+ -> String       -- ^ @contextDescription@ - textual description of what context the
+                 -- new message is being used in.
+ -> IO ContextId -- ^ returns an id that can be used to later remove entries
+                 -- ^ from the Statusbar.
+statusbarGetContextId self contextDescription =
+  withUTFString contextDescription $ \contextDescriptionPtr ->
+  {# call unsafe statusbar_get_context_id #}
+    (toStatusbar self)
+    contextDescriptionPtr
 
 type MessageId = {#type guint#}
 
--- | Push a new message on the Statusbar stack. It will
+-- | Pushes a new message onto the Statusbar's stack. It will
 -- be displayed as long as it is on top of the stack.
 --
-statusbarPush :: StatusbarClass sb => sb -> ContextId -> String -> IO MessageId
-statusbarPush sb context msg = withUTFString msg $ {#call statusbar_push#}
-  (toStatusbar sb) context
+statusbarPush :: StatusbarClass self => self
+ -> ContextId    -- ^ @contextId@ - the message's context id, as returned by
+                 -- 'statusbarGetContextId'.
+ -> String       -- ^ @text@ - the message to add to the statusbar.
+ -> IO MessageId -- ^ returns the message's new message id for use with
+                 -- 'statusbarRemove'.
+statusbarPush self contextId text =
+  withUTFString text $ \textPtr ->
+  {# call statusbar_push #}
+    (toStatusbar self)
+    contextId
+    textPtr
 
--- | Pops the topmost message that has the correct
--- context.
+-- | Removes the topmost message that has the correct context.
 --
-statusbarPop :: StatusbarClass sb => sb -> ContextId -> IO ()
-statusbarPop sb context = {#call statusbar_pop#} (toStatusbar sb) context
+statusbarPop :: StatusbarClass self => self
+ -> ContextId   -- ^ @contextId@ - the context identifier used when the
+                -- message was added.
+ -> IO ()
+statusbarPop self contextId =
+  {# call statusbar_pop #}
+    (toStatusbar self)
+     contextId
 
--- | Remove an entry within the stack.
+-- | Forces the removal of a message from a statusbar's stack. The exact
+-- @contextId@ and @messageId@ must be specified.
 --
-statusbarRemove :: StatusbarClass sb => sb -> ContextId -> MessageId -> IO ()
-statusbarRemove sb context message = {#call statusbar_remove#} (toStatusbar sb)
-  context message
+statusbarRemove :: StatusbarClass self => self
+ -> ContextId -- ^ @contextId@ - a context identifier.
+ -> MessageId -- ^ @messageId@ - a message identifier, as returned by
+              -- 'statusbarPush'.
+ -> IO ()
+statusbarRemove self contextId messageId =
+  {# call statusbar_remove #}
+    (toStatusbar self)
+    contextId
+    messageId
 
--- | Toggle the displaying of a resize grip.
+-- | Sets whether the statusbar has a resize grip. @True@ by default.
 --
-statusbarSetHasResizeGrip :: StatusbarClass sb => sb -> Bool -> IO ()
-statusbarSetHasResizeGrip sb set = {#call statusbar_set_has_resize_grip#}
-  (toStatusbar sb) (fromBool set)
+statusbarSetHasResizeGrip :: StatusbarClass self => self -> Bool -> IO ()
+statusbarSetHasResizeGrip self setting =
+  {# call statusbar_set_has_resize_grip #}
+    (toStatusbar self)
+    (fromBool setting)
 
--- | Query the displaying of the resize grip.
+-- | Returns whether the statusbar has a resize grip.
 --
-statusbarGetHasResizeGrip :: StatusbarClass sb => sb -> IO Bool
-statusbarGetHasResizeGrip sb = liftM toBool $
-  {#call unsafe statusbar_get_has_resize_grip#} (toStatusbar sb)
+statusbarGetHasResizeGrip :: StatusbarClass self => self -> IO Bool
+statusbarGetHasResizeGrip self =
+  liftM toBool $
+  {# call unsafe statusbar_get_has_resize_grip #}
+    (toStatusbar self)
 
 --------------------
 -- Signals
 
 -- | Called if a message is removed.
 --
-onTextPopped, afterTextPopped :: StatusbarClass sb => sb ->
-                                 (ContextId -> String -> IO ()) ->
-                                 IO (ConnectId sb)
+onTextPopped, afterTextPopped :: StatusbarClass self => self
+ -> (ContextId -> String -> IO ())
+ -> IO (ConnectId self)
 onTextPopped = connect_WORD_STRING__NONE "text-popped" False
 afterTextPopped = connect_WORD_STRING__NONE "text-popped" True
 
 -- | Called if a message is pushed on top of the
 -- stack.
 --
-onTextPushed, afterTextPushed :: StatusbarClass sb => sb ->
-                                 (ContextId -> String -> IO ()) ->
-                                 IO (ConnectId sb)
+onTextPushed, afterTextPushed :: StatusbarClass self => self
+ -> (ContextId -> String -> IO ())
+ -> IO (ConnectId self)
 onTextPushed = connect_WORD_STRING__NONE "text-pushed" False
 afterTextPushed = connect_WORD_STRING__NONE "text-pushed" True
-

Index: AccelLabel.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/AccelLabel.chs,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- AccelLabel.chs	25 Feb 2005 01:11:32 -0000	1.3
+++ AccelLabel.chs	15 Mar 2005 19:59:09 -0000	1.4
@@ -24,10 +24,10 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- A label which displays an accelerator key on the right of the text.
+-- A label which displays an accelerator key on the right of the text
 --
 module Graphics.UI.Gtk.Display.AccelLabel (
--- * Description
+-- * Detail
 -- 
 -- | The 'AccelLabel' widget is a subclass of 'Label' that also displays an
 -- accelerator key on the right of the label text, e.g. \'Ctl+S\'. It is
@@ -90,28 +90,35 @@
 --------------------
 -- Constructors
 
--- | Create a new label with an accelerator key.
+-- | Creates a new 'AccelLabel'.
 --
 accelLabelNew :: String -> IO AccelLabel
-accelLabelNew str = withUTFString str $ \strPtr -> makeNewObject mkAccelLabel $ 
-  liftM castPtr $ {#call unsafe accel_label_new#} strPtr
+accelLabelNew string =
+  makeNewObject mkAccelLabel $ liftM castPtr $
+  withUTFString string $ \stringPtr ->
+  {# call unsafe accel_label_new #}
+    stringPtr
 
 --------------------
 -- Methods
 
--- | Set the key name from the activation
--- signal of another widget.
+-- | Sets the widget to be monitored by this accelerator label.
 --
-accelLabelSetAccelWidget :: (AccelLabelClass acl, WidgetClass w) => acl -> w ->
-                            IO ()
-accelLabelSetAccelWidget acl w = {#call accel_label_set_accel_widget#}
-  (toAccelLabel acl) (toWidget w)
+accelLabelSetAccelWidget :: (AccelLabelClass self, WidgetClass accelWidget) => self
+ -> accelWidget -- ^ @accelWidget@ - the widget to be monitored.
+ -> IO ()
+accelLabelSetAccelWidget self accelWidget =
+  {# call accel_label_set_accel_widget #}
+    (toAccelLabel self)
+    (toWidget accelWidget)
 
--- | Fetches the widget monitored by this accelerator label, or Nothing if it
--- has not bee set.
+-- | Fetches the widget monitored by this accelerator label. See
+-- 'accelLabelSetAccelWidget'.
 --
-accelLabelGetAccelWidget :: AccelLabelClass acl => acl -> IO (Maybe Widget)
-accelLabelGetAccelWidget acl = do
-  wPtr <- {#call unsafe accel_label_get_accel_widget#} (toAccelLabel acl)
-  if wPtr==nullPtr then return Nothing else liftM Just $
-    makeNewObject mkWidget (return wPtr)
+accelLabelGetAccelWidget :: AccelLabelClass self => self
+ -> IO (Maybe Widget) -- ^ returns the object monitored by the accelerator
+                      -- label, or @Nothing@.
+accelLabelGetAccelWidget self =
+  maybeNull (makeNewObject mkWidget) $
+  {# call unsafe accel_label_get_accel_widget #}
+    (toAccelLabel self)

Index: Label.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Label.chs,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- Label.chs	13 Mar 2005 19:34:32 -0000	1.5
+++ Label.chs	15 Mar 2005 19:59:09 -0000	1.6
@@ -24,10 +24,10 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- A widget that displays a small to medium amount of text.
+-- A widget that displays a small to medium amount of text
 --
 module Graphics.UI.Gtk.Display.Label (
--- * Description
+-- * Detail
 -- 
 -- | The 'Label' widget displays a small amount of text. As the name implies,
 -- most labels are used to label another widget such as a 'Button', a
@@ -175,39 +175,65 @@
 --------------------
 -- Constructors
 
--- | Create a new label widget.
+-- | Creates a new label with the given text inside it. You can pass @Nothing@
+-- to get an empty label widget.
 --
 labelNew :: Maybe String -> IO Label
-labelNew str = makeNewObject mkLabel $ liftM castPtr $
-  case str of
-    Nothing    -> {#call label_new#} nullPtr
-    (Just str) -> withUTFString str {#call label_new#}
+labelNew str =
+  makeNewObject mkLabel $ liftM castPtr $
+  maybeWith withUTFString str $ \strPtr ->
+  {# call label_new #}
+    strPtr
 
--- | Create a new label widget with accelerator key.
+-- | Creates a new 'Label', containing the given text.
 --
--- * Each underscore in @str@ is converted into an underlined character in the
---   label. Entering this character will activate the label widget or any other
---   widget set with 'labelSetMnemonicWidget'.
+-- If characters in @text@ are preceded by an underscore, they are
+-- underlined. If you need a literal underscore character in a label, use
+-- \'__\' (two underscores). The first underlined character represents a
+-- keyboard accelerator called a mnemonic. The mnemonic key can be used to
+-- activate another widget, chosen automatically, or explicitly using
+-- 'labelSetMnemonicWidget'.
 --
-labelNewWithMnemonic :: String -> IO Label
-labelNewWithMnemonic str = makeNewObject mkLabel $ liftM castPtr $
-  withUTFString str {#call label_new_with_mnemonic#}
+-- If 'labelSetMnemonicWidget' is not called, then the first activatable
+-- ancestor of the 'Label' will be chosen as the mnemonic widget. For instance,
+-- if the label is inside a button or menu item, the button or menu item will
+-- automatically become the mnemonic widget and be activated by the mnemonic.
+--
+labelNewWithMnemonic :: 
+    String   -- ^ @text@ - The text of the label, with an underscore in front
+             -- of the mnemonic character
+ -> IO Label
+labelNewWithMnemonic str =
+  makeNewObject mkLabel $ liftM castPtr $
+  withUTFString str $ \strPtr ->
+  {# call label_new_with_mnemonic #}
+    strPtr
 
 --------------------
 -- Methods
 
--- | Set the text the label widget shows. 
+-- | Sets the text within the 'Label' widget. It overwrites any text that was
+-- there before.
 --
-labelSetText :: LabelClass l => l -> String -> IO ()
-labelSetText l str =
-  withUTFString str $ {#call label_set_text#} (toLabel l)
+-- This will also clear any previously set mnemonic accelerators.
+--
+labelSetText :: LabelClass self => self -> String -> IO ()
+labelSetText self str =
+  withUTFString str $ \strPtr ->
+  {# call label_set_text #}
+    (toLabel self)
+    strPtr
 
--- | The label is interpreted as including embedded underlines and\/or Pango
--- markup depending on the markup and underline properties.
+-- | Sets the text of the label. The label is interpreted as including
+-- embedded underlines and\/or Pango markup depending on the markup and
+-- underline properties.
 --
-labelSetLabel :: LabelClass l => l -> String -> IO ()
-labelSetLabel l str =
-  withUTFString str $ {#call label_set_label#} (toLabel l)
+labelSetLabel :: LabelClass self => self -> String -> IO ()
+labelSetLabel self str =
+  withUTFString str $ \strPtr ->
+  {# call label_set_label #}
+    (toLabel self)
+    strPtr
 
 {-
 -- | Set the text attributes.
@@ -215,174 +241,293 @@
 -- labelSetAttributes :: LabelClass l => PangoAttrList -> IO ()
 -}
 
--- | Set the label to a markup string.
+-- | Parses @str@ which is marked up with the Pango text markup language,
+-- setting the label's text and attribute list based on the parse results. If
+-- the @str@ is external data, you may need to escape it.
 --
-labelSetMarkup :: LabelClass l => l -> Markup -> IO ()
-labelSetMarkup l str =
-  withUTFString str $ {#call label_set_markup#} (toLabel l)
+labelSetMarkup :: LabelClass self => self
+ -> Markup -- ^ @str@ - a markup string (see Pango markup format)
+ -> IO ()
+labelSetMarkup self str =
+  withUTFString str $ \strPtr ->
+  {# call label_set_markup #}
+    (toLabel self)
+    strPtr
 
--- | Set the label to a markup string and interpret keyboard accelerators.
+-- | Parses @str@ which is marked up with the Pango text markup language,
+-- setting the label's text and attribute list based on the parse results. If
+-- characters in @str@ are preceded by an underscore, they are underlined
+-- indicating that they represent a keyboard accelerator called a mnemonic.
 --
-labelSetMarkupWithMnemonic :: LabelClass l => l -> Markup -> IO ()
-labelSetMarkupWithMnemonic l str =
-  withUTFString str $ {#call label_set_markup_with_mnemonic#} (toLabel l)
+-- The mnemonic key can be used to activate another widget, chosen
+-- automatically, or explicitly using 'labelSetMnemonicWidget'.
+--
+labelSetMarkupWithMnemonic :: LabelClass self => self
+ -> Markup -- ^ @str@ - a markup string (see Pango markup format)
+ -> IO ()
+labelSetMarkupWithMnemonic self str =
+  withUTFString str $ \strPtr ->
+  {# call label_set_markup_with_mnemonic #}
+    (toLabel self)
+    strPtr
 
 -- | Underline parts of the text, odd indices of the list represent underlined
 -- parts.
 --
 labelSetPattern :: LabelClass l => l -> [Int] -> IO ()
-labelSetPattern l list =
-  withUTFString str $ {#call label_set_pattern#} (toLabel l)
+labelSetPattern self list =
+  withUTFString str $
+  {# call label_set_pattern #}
+    (toLabel self)
   where
     str = concat $ zipWith replicate list (cycle ['_',' '])
 
--- | Set the justification of the label.
+-- | Sets the alignment of the lines in the text of the label relative to each
+-- other. 'JustifyLeft' is the default value when the widget is first created
+-- with 'labelNew'. If you instead want to set the alignment of the label as a
+-- whole, use 'miscSetAlignment' instead. 'labelSetJustify' has no effect on
+-- labels containing only a single line.
 --
-labelSetJustify :: LabelClass l => l -> Justification -> IO ()
-labelSetJustify l j = 
-  {#call label_set_justify#} (toLabel l) ((fromIntegral.fromEnum) j)
+labelSetJustify :: LabelClass self => self -> Justification -> IO ()
+labelSetJustify self jtype =
+  {# call label_set_justify #}
+    (toLabel self)
+    ((fromIntegral . fromEnum) jtype)
 
--- | Get the justification of the label.
+-- | Returns the justification of the label. See 'labelSetJustify'.
 --
-labelGetJustify :: LabelClass l => l -> IO Justification
-labelGetJustify l =
-  liftM (toEnum.fromIntegral) $ {#call unsafe label_get_justify#} (toLabel l)
+labelGetJustify :: LabelClass self => self -> IO Justification
+labelGetJustify self =
+  liftM (toEnum . fromIntegral) $
+  {# call unsafe label_get_justify #}
+    (toLabel self)
 
--- | Gets the "PangoLayout" used to display the label.
+-- | Gets the 'Layout' used to display the label. The layout is useful to e.g.
+-- convert text positions to pixel positions, in combination with
+-- 'labelGetLayoutOffsets'.
 --
-labelGetLayout :: LabelClass l => l -> IO PangoLayout
-labelGetLayout l =
-  makeNewGObject mkPangoLayout $ {#call unsafe label_get_layout#} (toLabel l)
+labelGetLayout :: LabelClass self => self
+ -> IO PangoLayout -- ^ returns the 'Layout' for this label
+labelGetLayout self =
+  makeNewGObject mkPangoLayout $
+  {# call unsafe label_get_layout #}
+    (toLabel self)
 
--- | Set wether lines should be wrapped (@True@) or truncated (@False@).
+-- | Toggles line wrapping within the 'Label' widget. @True@ makes it break
+-- lines if text exceeds the widget's size. @False@ lets the text get cut off
+-- by the edge of the widget if it exceeds the widget size.
 --
-labelSetLineWrap :: LabelClass l => l -> Bool -> IO ()
-labelSetLineWrap l w = {#call label_set_line_wrap#} (toLabel l) (fromBool w)
+labelSetLineWrap :: LabelClass self => self
+ -> Bool  -- ^ @wrap@ - the setting
+ -> IO ()
+labelSetLineWrap self wrap =
+  {# call label_set_line_wrap #}
+    (toLabel self)
+    (fromBool wrap)
 
--- | Returns whether lines in the label are automatically wrapped.
+-- | Returns whether lines in the label are automatically wrapped. See
+-- 'labelSetLineWrap'.
 --
-labelGetLineWrap :: LabelClass l => l -> IO Bool
-labelGetLineWrap l = liftM toBool $
-  {#call unsafe label_get_line_wrap#} (toLabel l)
+labelGetLineWrap :: LabelClass self => self
+ -> IO Bool -- ^ returns @True@ if the lines of the label are automatically
+            -- wrapped.
+labelGetLineWrap self =
+  liftM toBool $
+  {# call unsafe label_get_line_wrap #}
+    (toLabel self)
 
--- | Get starting cooridinates of text rendering.
+-- | Obtains the coordinates where the label will draw the 'Layout'
+-- representing the text in the label; useful to convert mouse events into
+-- coordinates inside the 'Layout', e.g. to take some action if some part of
+-- the label is clicked. Of course you will need to create a 'EventBox' to
+-- receive the events, and pack the label inside it, since labels are a
+-- \'NoWindow\' widget.
 --
-labelGetLayoutOffsets :: LabelClass l => l -> IO (Int,Int)
-labelGetLayoutOffsets l =
-  alloca (\xPtr ->
-    alloca (\yPtr -> do
-      {#call unsafe label_get_layout_offsets#} (toLabel l) xPtr yPtr
-      x <- peek xPtr
-      y <- peek yPtr
-      return (fromIntegral x,fromIntegral y)
-    )
-  )
+labelGetLayoutOffsets :: LabelClass self => self -> IO (Int,Int)
+labelGetLayoutOffsets self =
+  alloca $ \xPtr ->
+  alloca $ \yPtr -> do
+  {# call unsafe label_get_layout_offsets #}
+    (toLabel self)
+    xPtr
+    yPtr
+  x <- peek xPtr
+  y <- peek yPtr
+  return (fromIntegral x,fromIntegral y)
 
 -- | KeyVal is a synonym for a hot key number.
 --
 type KeyVal = {#type guint#}
 
--- | Get the keyval for the underlined character in the label.
+-- | If the label has been set so that it has an mnemonic key this function
+-- returns the keyval used for the mnemonic accelerator.
 --
-labelGetMnemonicKeyval :: LabelClass l => l -> IO KeyVal
-labelGetMnemonicKeyval l = 
-  {#call unsafe label_get_mnemonic_keyval#} (toLabel l)
+labelGetMnemonicKeyval :: LabelClass self => self -> IO KeyVal
+labelGetMnemonicKeyval self =
+  {# call unsafe label_get_mnemonic_keyval #}
+    (toLabel self)
 
--- | Get whether the text selectable.
+-- | Gets whether the text selectable.
 --
-labelGetSelectable :: LabelClass l => l -> IO Bool
-labelGetSelectable l = liftM toBool $ 
-  {#call unsafe label_get_selectable#} (toLabel l)
+labelGetSelectable :: LabelClass self => self
+ -> IO Bool -- ^ returns @True@ if the user can copy text from the label
+labelGetSelectable self =
+  liftM toBool $
+  {# call unsafe label_get_selectable #}
+    (toLabel self)
 
 -- | Sets whether the text of the label contains markup in Pango's text markup
--- language.
+-- language. See 'labelSetMarkup'.
 --
-labelSetUseMarkup :: LabelClass l => l -> Bool -> IO ()
-labelSetUseMarkup l useMarkup =
-  {#call label_set_use_markup#} (toLabel l) (fromBool useMarkup)
+labelSetUseMarkup :: LabelClass self => self
+ -> Bool  -- ^ @setting@ - @True@ if the label's text should be parsed for
+          -- markup.
+ -> IO ()
+labelSetUseMarkup self setting =
+  {# call label_set_use_markup #}
+    (toLabel self)
+    (fromBool setting)
 
 -- | Returns whether the label's text is interpreted as marked up with the
--- Pango text markup language.
+-- Pango text markup language. See 'labelSetUseMarkup'.
 --
-labelGetUseMarkup :: LabelClass l => l -> IO Bool
-labelGetUseMarkup l = liftM toBool $
-  {#call unsafe label_get_use_markup#} (toLabel l)
+labelGetUseMarkup :: LabelClass self => self
+ -> IO Bool -- ^ returns @True@ if the label's text will be parsed for markup.
+labelGetUseMarkup self =
+  liftM toBool $
+  {# call unsafe label_get_use_markup #}
+    (toLabel self)
 
--- | If @True@, an underline in the text indicates the next character should
--- be used for the mnemonic accelerator key.
+-- | If @True@, an underline in the text indicates the next character should be
+-- used for the mnemonic accelerator key.
 --
-labelSetUseUnderline :: LabelClass l => l -> Bool -> IO ()
-labelSetUseUnderline l useUnderline =
-  {#call label_set_use_underline#} (toLabel l) (fromBool useUnderline)
+labelSetUseUnderline :: LabelClass self => self -> Bool -> IO ()
+labelSetUseUnderline self useUnderline =
+  {# call label_set_use_underline #}
+    (toLabel self)
+    (fromBool useUnderline)
 
 -- | Returns whether an embedded underline in the label indicates a mnemonic.
+-- See 'labelSetUseUnderline'.
 --
-labelGetUseUnderline :: LabelClass l => l -> IO Bool
-labelGetUseUnderline l = liftM toBool $
-  {#call unsafe label_get_use_underline#} (toLabel l)
+labelGetUseUnderline :: LabelClass self => self -> IO Bool
+labelGetUseUnderline self =
+  liftM toBool $
+  {# call unsafe label_get_use_underline #}
+    (toLabel self)
 
--- | Get the text stored in the label. This does not include any embedded
--- underlines indicating mnemonics or Pango markup.
+-- | Gets the text from a label widget, as displayed on the screen. This
+-- does not include any embedded underlines indicating mnemonics or Pango
+-- markup. (See 'labelGetLabel')
 --
-labelGetText :: LabelClass l => l -> IO String
-labelGetText l = {#call unsafe label_get_text#} (toLabel l) >>= peekUTFString
+labelGetText :: LabelClass self => self -> IO String
+labelGetText self =
+  {# call unsafe label_get_text #}
+    (toLabel self)
+  >>= peekUTFString
 
--- | Get the text from a label widget including any embedded underlines
--- indicating mnemonics and Pango markup.
+-- | Gets the text from a label widget including any embedded underlines
+-- indicating mnemonics and Pango markup. (See 'labelGetText').
 --
-labelGetLabel :: LabelClass l => l -> IO String
-labelGetLabel l = {#call unsafe label_get_label#} (toLabel l) >>= peekUTFString
+labelGetLabel :: LabelClass self => self -> IO String
+labelGetLabel self =
+  {# call unsafe label_get_label #}
+    (toLabel self)
+  >>= peekUTFString
 
--- | Select a region in the label.
+-- | Selects a range of characters in the label, if the label is selectable.
+-- See 'labelSetSelectable'. If the label is not selectable, this function has
+-- no effect. If @startOffset@ or @endOffset@ are -1, then the end of the label
+-- will be substituted.
 --
-labelSelectRegion :: LabelClass l => l -> Int -> Int -> IO ()
-labelSelectRegion l start end = {#call label_select_region#} (toLabel l) 
-  (fromIntegral start) (fromIntegral end)
+labelSelectRegion :: LabelClass self => self
+ -> Int   -- ^ @startOffset@ - start offset
+ -> Int   -- ^ @endOffset@ - end offset
+ -> IO ()
+labelSelectRegion self startOffset endOffset =
+  {# call label_select_region #}
+    (toLabel self)
+    (fromIntegral startOffset)
+    (fromIntegral endOffset)
 
 -- | Gets the selected range of characters in the label, if any. If there is
 -- a range selected the result is the start and end of the selection as
 -- character offsets.
 --
-labelGetSelectionBounds :: LabelClass l => l -> IO (Maybe (Int, Int))
-labelGetSelectionBounds l =
-  alloca $ \startPtr -> alloca $ \endPtr -> do
+labelGetSelectionBounds :: LabelClass self => self
+ -> IO (Maybe (Int, Int))
+labelGetSelectionBounds self =
+  alloca $ \startPtr ->
+  alloca $ \endPtr -> do
   isSelection <-
-    {#call unsafe label_get_selection_bounds#} (toLabel l) startPtr endPtr
-  if toBool isSelection
+    liftM toBool $
+    {# call unsafe label_get_selection_bounds #}
+    (toLabel self)
+    startPtr
+    endPtr
+  if isSelection
     then do start <- peek startPtr
             end <- peek endPtr
 	    return $ Just $ (fromIntegral start, fromIntegral end)
     else return Nothing
 
--- | Set an explicit widget for which to emit the \"mnemonic_activate\" signal
--- if an underlined character is pressed.
+-- | If the label has been set so that it has an mnemonic key (using i.e.
+-- 'labelSetMarkupWithMnemonic', 'labelSetTextWithMnemonic',
+-- 'labelNewWithMnemonic' or the \"use_underline\" property) the label can be
+-- associated with a widget that is the target of the mnemonic. When the label
+-- is inside a widget (like a 'Button' or a 'Notebook' tab) it is automatically
+-- associated with the correct widget, but sometimes (i.e. when the target is a
+-- 'Entry' next to the label) you need to set it explicitly using this
+-- function.
 --
-labelSetMnemonicWidget :: (LabelClass l, WidgetClass w) => l -> w -> IO ()
-labelSetMnemonicWidget l w = 
-  {#call unsafe label_set_mnemonic_widget#} (toLabel l) (toWidget w)
-
--- | Retrieves the target of the mnemonic (keyboard shortcut) of this label,
--- or Nothing if none has been set and the default algorithm will be used.
+-- The target widget will be accelerated by emitting \"mnemonic_activate\"
+-- on it. The default handler for this signal will activate the widget if there
+-- are no mnemonic collisions and toggle focus between the colliding widgets
+-- otherwise.
 --
-labelGetMnemonicWidget :: LabelClass l => l -> IO (Maybe Widget)
-labelGetMnemonicWidget l = do
-  widgetPtr <- {#call unsafe label_get_mnemonic_widget#} (toLabel l)
-  if widgetPtr == nullPtr
-    then return Nothing
-    else liftM Just $ makeNewObject mkWidget (return widgetPtr)
+labelSetMnemonicWidget :: (LabelClass self, WidgetClass widget) => self
+ -> widget -- ^ @widget@ - the target 'Widget'
+ -> IO ()
+labelSetMnemonicWidget self widget =
+  {# call unsafe label_set_mnemonic_widget #}
+    (toLabel self)
+    (toWidget widget)
 
--- | Make a label text selectable.
+-- | Retrieves the target of the mnemonic (keyboard shortcut) of this label.
+-- See 'labelSetMnemonicWidget'.
 --
-labelSetSelectable :: LabelClass l => l -> Bool -> IO ()
-labelSetSelectable l s =
-  {#call unsafe label_set_selectable#} (toLabel l) (fromBool s)
+labelGetMnemonicWidget :: LabelClass self => self
+ -> IO (Maybe Widget) -- ^ returns the target of the label's mnemonic, or
+                      -- @Nothing@ if none has been set and the default
+                      -- algorithm will be used.
+labelGetMnemonicWidget self =
+  maybeNull (makeNewObject mkWidget) $
+  {# call unsafe label_get_mnemonic_widget #}
+    (toLabel self)
 
--- | Set the label to a markup string and interpret keyboard accelerators.
+-- | Selectable labels allow the user to select text from the label, for
+-- copy-and-paste.
 --
-labelSetTextWithMnemonic :: LabelClass l => l -> String -> IO ()
-labelSetTextWithMnemonic l str =
-  withUTFString str $ {#call label_set_text_with_mnemonic#} (toLabel l)
+labelSetSelectable :: LabelClass self => self
+ -> Bool  -- ^ @setting@ - @True@ to allow selecting text in the label
+ -> IO ()
+labelSetSelectable self setting =
+  {# call unsafe label_set_selectable #}
+    (toLabel self)
+    (fromBool setting)
 
+-- | Sets the label's text from the given string. If characters in the string are
+-- preceded by an underscore, they are underlined indicating that they
+-- represent a keyboard accelerator called a mnemonic. The mnemonic key can be
+-- used to activate another widget, chosen automatically, or explicitly using
+-- 'labelSetMnemonicWidget'.
+--
+labelSetTextWithMnemonic :: LabelClass self => self -> String -> IO ()
+labelSetTextWithMnemonic self str =
+  withUTFString str $ \strPtr ->
+  {# call label_set_text_with_mnemonic #}
+    (toLabel self)
+    strPtr
 
 --------------------
 -- Properties