Re-format function arguments for Haddock. Add blurb about compilation…

… speed.
deech · Oct 16, 2015 · 771441d · 771441d
1 parent 11fec87
commit 771441d
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 45 deletions.
diff --git a/src/Graphics/UI/FLTK/LowLevel/Box.chs b/src/Graphics/UI/FLTK/LowLevel/Box.chs
@@ -34,11 +34,12 @@ import Graphics.UI.FLTK.LowLevel.Widget
 {# fun Fl_OverriddenBox_New as overriddenBoxNew' { `Int',`Int',`Int',`Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_Box_New_WithBoxtype as boxNewWithBoxtype' {cFromEnum `Boxtype',  `Int',`Int',`Int',`Int',unsafeToCString `String'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenBox_New_WithBoxtype as overriddenBoxNewWithBoxtype' {cFromEnum `Boxtype',  `Int',`Int',`Int',`Int',unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-boxCustom :: Rectangle ->                       -- ^ The bounds of this box
-             Maybe String ->                    -- ^ Optional label
-             Maybe (Ref Box -> IO ()) ->        -- ^ Optional custom box drawing function
-             Maybe (CustomWidgetFuncs Box) ->   -- ^ Optional widget overrides
-             IO (Ref Box)
+
+boxCustom :: Rectangle                     -- ^ The bounds of this box
+          -> Maybe String                  -- ^ Optional label
+          -> Maybe (Ref Box -> IO ())      -- ^ Optional custom box drawing function
+          -> Maybe (CustomWidgetFuncs Box) -- ^ Optional widget overrides
+          -> IO (Ref Box)
 boxCustom rectangle l' draw' funcs' =
   widgetMaker
     rectangle

diff --git a/src/Graphics/UI/FLTK/LowLevel/Button.chs b/src/Graphics/UI/FLTK/LowLevel/Button.chs
@@ -33,11 +33,11 @@ import Graphics.UI.FLTK.LowLevel.Hierarchy
 {# fun Fl_Button_New_WithLabel as widgetNewWithLabel' { `Int',`Int',`Int',`Int', unsafeToCString `String'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenButton_New_WithLabel as overriddenWidgetNewWithLabel' { `Int',`Int',`Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenButton_New as overriddenWidgetNew' { `Int',`Int',`Int',`Int', id `Ptr ()'} -> `Ptr ()' id #}
-buttonCustom :: Rectangle ->                         -- ^ The bounds of this button
-                Maybe String ->                      -- ^ The button label
-                Maybe (Ref Button -> IO ()) ->       -- ^ Optional custom drawing function
-                Maybe (CustomWidgetFuncs Button) ->  -- ^ Optional custom widget functions
-                IO (Ref Button)
+buttonCustom :: Rectangle                         -- ^ The bounds of this button
+             -> Maybe String                      -- ^ The button label
+             -> Maybe (Ref Button -> IO ())       -- ^ Optional custom drawing function
+             -> Maybe (CustomWidgetFuncs Button)  -- ^ Optional custom widget functions
+             -> IO (Ref Button)
 buttonCustom rectangle l' draw' funcs' =
   widgetMaker
     rectangle

diff --git a/src/Graphics/UI/FLTK/LowLevel/DoubleWindow.chs b/src/Graphics/UI/FLTK/LowLevel/DoubleWindow.chs
@@ -31,13 +31,13 @@ import C2HS hiding (cFromEnum, toBool,cToEnum)
 {# fun Fl_OverriddenDouble_Window_NewXY as overriddenWindowNewXY' {`Int',`Int', `Int', `Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenDouble_Window_NewXY_WithLabel as overriddenWindowNewXYWithLabel' { `Int',`Int',`Int',`Int',unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenDouble_Window_New_WithLabel as overriddenWindowNewWithLabel' { `Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-doubleWindowCustom :: Size ->                              -- ^ Size of this window
-                      Maybe Position ->                    -- ^ Optional position of this window
-                      Maybe String ->                      -- ^ Optional label
-                      Maybe (Ref DoubleWindow -> IO ()) -> -- ^ Optional table drawing routine
-                      CustomWidgetFuncs DoubleWindow ->    -- ^ Custom widget overrides
-                      CustomWindowFuncs DoubleWindow ->    -- ^ Custom window overrides
-                      IO (Ref DoubleWindow)
+doubleWindowCustom :: Size                              -- ^ Size of this window
+                   -> Maybe Position                    -- ^ Optional position of this window
+                   -> Maybe String                      -- ^ Optional label
+                   -> Maybe (Ref DoubleWindow -> IO ()) -- ^ Optional table drawing routine
+                   -> CustomWidgetFuncs DoubleWindow    -- ^ Custom widget overrides
+                   -> CustomWindowFuncs DoubleWindow    -- ^ Custom window overrides
+                   -> IO (Ref DoubleWindow)
 doubleWindowCustom size position title draw' customWidgetFuncs' customWindowFuncs' =
   windowMaker
     size

diff --git a/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs b/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs
@@ -36,6 +36,10 @@ module Graphics.UI.FLTK.LowLevel.FLTKHS
          --
          -- $APIGuide
 
+         -- * Slow Compilation Issues
+         --
+         -- $Compilation
+
          -- * Core Types
          module Graphics.UI.FLTK.LowLevel.Fl_Types,
          -- * Widgets
@@ -636,6 +640,34 @@ import Graphics.UI.FLTK.LowLevel.ColorChooser
 -- being able to get at the default implementation out-weighs the trap the user might fall into. If this becomes a pervasive problem the author is
 -- open to removing this functionality.
 --
+
+-- $Compilation
+--
+-- As described above, the API emulates multiple dispatch using type-level programming and typeclasseses. While this is makes for a nice API it has also
+-- slowed down compilation of executables much more than expected. This is especially true in the GHC 7.10.x series in which the step where GHC specialises typeclass
+-- function calls to concrete types has apparently taken a *huge* compile-time performance hit.
+--
+-- To clarify the time taken to compile the library itself has not changed, but applications that use the library to create executables are taking a lot
+-- longer (almost 3x compared to GHC 7.8.x) to compile. To further emphasize, there does not appear to be any runtime performance issues. This is only a
+-- compile time problem.
+--
+-- To preserve the user's and the author's sanity a flag `fastCompile` has been introduced to this package and to the <http://hackage.haskell.org/fltkhs-fluid-examples fltkhs-fluid-examples>.
+-- This flag which tells the compiler to skip the specialising step when compiling executables, dramatically decreases compile time but also bloats the resulting executable size and
+-- probably makes runtime performance much slower. In this package and <http://hackage.haskell.org/fltkhs-fluid-examples fltkhs-fluid-examples> it is enabled by default, since the executables are just
+-- demos that are not meant to show off performance. To disable this flag, tell Cabal to ignore it during the `configure` step:
+--
+-- @
+-- cabal configure -f-fastCompile
+-- @
+--
+-- In the <https://github.com/deech/fltkhs-hello-world fltkhs> and the <https://github.com/deech/fltkhs-fluid-hello-world fltkhs-fluid> project skeletons this flag is /disabled/ by
+-- default to provide the best runtime performance. To enable the flag for a smoother development workflow, tell Cabal to enable it during the `configure` step:
+--
+-- @
+-- cabal configure -f fastCompile
+-- @
+
+
 -- =File Layout
 -- @
 -- Root

diff --git a/src/Graphics/UI/FLTK/LowLevel/GlWindow.chs b/src/Graphics/UI/FLTK/LowLevel/GlWindow.chs
@@ -31,13 +31,13 @@ import C2HS hiding (cFromEnum, toBool,cToEnum)
 {# fun Fl_OverriddenGl_Window_NewXY as overriddenWindowNewXY' {`Int',`Int', `Int', `Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenGl_Window_NewXY_WithLabel as overriddenWindowNewXYWithLabel' { `Int',`Int',`Int',`Int',unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenGl_Window_New_WithLabel as overriddenWindowNewWithLabel' { `Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-glWindowCustom :: Size ->                           -- ^ The size of this window
-                  Maybe Position ->                 -- ^ The position of this window
-                  Maybe String ->                   -- ^ The window label
-                  Maybe (Ref GlWindow -> IO ()) ->  -- ^ Optional custom drawing function
-                  CustomWidgetFuncs GlWindow ->     -- ^ other custom widget functions
-                  CustomWindowFuncs GlWindow ->     -- ^ Other custom window functions
-                  IO (Ref GlWindow)
+glWindowCustom :: Size                           -- ^ The size of this window
+               -> Maybe Position                 -- ^ The position of this window
+               -> Maybe String                   -- ^ The window label
+               -> Maybe (Ref GlWindow -> IO ())  -- ^ Optional custom drawing function
+               -> CustomWidgetFuncs GlWindow     -- ^ other custom widget functions
+               -> CustomWindowFuncs GlWindow     -- ^ Other custom window functions
+               -> IO (Ref GlWindow)
 glWindowCustom size position title draw' customWidgetFuncs' customWindowFuncs' =
   windowMaker
     size

diff --git a/src/Graphics/UI/FLTK/LowLevel/SingleWindow.chs b/src/Graphics/UI/FLTK/LowLevel/SingleWindow.chs
@@ -30,13 +30,13 @@ import C2HS hiding (cFromEnum, toBool,cToEnum)
 {# fun Fl_OverriddenSingle_Window_NewXY as overriddenWindowNewXY' {`Int',`Int', `Int', `Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenSingle_Window_NewXY_WithLabel as overriddenWindowNewXYWithLabel' { `Int',`Int',`Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenSingle_Window_New_WithLabel as overriddenWindowNewWithLabel' { `Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-singleWindowCustom :: Size ->                                 -- ^ Size of this window
-                      Maybe Position ->                       -- ^ Optional position of this window
-                      Maybe String ->                         -- ^ Optional label
-                      Maybe (Ref SingleWindow -> IO ()) ->    -- ^ Optional custom drawing function
-                      CustomWidgetFuncs SingleWindow ->       -- ^ Custom widget overrides
-                      CustomWindowFuncs SingleWindow ->       -- ^ Custom window overrides
-                      IO (Ref SingleWindow)
+singleWindowCustom :: Size                                 -- ^ Size of this window
+                   -> Maybe Position                       -- ^ Optional position of this window
+                   -> Maybe String                         -- ^ Optional label
+                   -> Maybe (Ref SingleWindow -> IO ())    -- ^ Optional custom drawing function
+                   -> CustomWidgetFuncs SingleWindow       -- ^ Custom widget overrides
+                   -> CustomWindowFuncs SingleWindow       -- ^ Custom window overrides
+                   -> IO (Ref SingleWindow)
 singleWindowCustom size position title draw' customWidgetFuncs' customWindowFuncs' =
   windowMaker
     size

diff --git a/src/Graphics/UI/FLTK/LowLevel/Table.chs b/src/Graphics/UI/FLTK/LowLevel/Table.chs
@@ -120,13 +120,13 @@ tableCustomFunctionStruct draw' drawCell' customWidgetFuncs' customTableFuncs' =
 
 {# fun Fl_Table_New as tableNew' {  `Int',`Int', `Int', `Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_Table_New_WithLabel as tableNewWithLabel' { `Int',`Int',`Int',`Int',unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-tableCustom :: Rectangle ->                                                            -- ^ Bounds of this table
-               Maybe String ->                                                         -- ^ Optional label
-               Maybe (Ref Table -> IO ()) ->                                           -- ^ Optional custom table drawing function
-               (Ref Table -> TableContext -> TableCoordinate -> Rectangle -> IO ()) -> -- ^ Custom table cell drawing function
-               CustomWidgetFuncs Table ->                                              -- ^ Widget overrides
-               CustomTableFuncs Table ->                                               -- ^ Table overrides
-               IO (Ref Table)
+tableCustom :: Rectangle                                                            -- ^ Bounds of this table
+            -> Maybe String                                                         -- ^ Optional label
+            -> Maybe (Ref Table -> IO ())                                           -- ^ Optional custom table drawing function
+            -> (Ref Table -> TableContext -> TableCoordinate -> Rectangle -> IO ()) -- ^ Custom table cell drawing function
+            -> CustomWidgetFuncs Table                                              -- ^ Widget overrides
+            -> CustomTableFuncs Table                                               -- ^ Table overrides
+            -> IO (Ref Table)
 tableCustom rectangle label' draw' drawCell' customWidgetFuncs' customTableFuncs' =
     do
       let (x_pos, y_pos, width, height) = fromRectangle rectangle

diff --git a/src/Graphics/UI/FLTK/LowLevel/Window.chs b/src/Graphics/UI/FLTK/LowLevel/Window.chs
@@ -121,13 +121,13 @@ windowMaker (Size (Width w) (Height h))
 {# fun Fl_OverriddenWindow_NewXY as overriddenWindowNewXY' {`Int',`Int', `Int', `Int', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenWindow_NewXY_WithLabel as overriddenWindowNewXYWithLabel' { `Int',`Int',`Int',`Int',unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
 {# fun Fl_OverriddenWindow_New_WithLabel as overriddenWindowNewWithLabel' { `Int',`Int', unsafeToCString `String', id `Ptr ()'} -> `Ptr ()' id #}
-windowCustom :: Size ->                        -- ^ Size of this window
-                Maybe Position ->              -- ^ Optional position of this window
-                Maybe String ->                -- ^ Optional label
-                Maybe (Ref Window -> IO ()) -> -- ^ Optional table drawing routine
-                CustomWidgetFuncs Window ->    -- ^ Custom widget overrides
-                CustomWindowFuncs Window ->    -- ^ Custom window overrides
-                IO (Ref Window)
+windowCustom :: Size                        -- ^ Size of this window
+             -> Maybe Position              -- ^ Optional position of this window
+             -> Maybe String                -- ^ Optional label
+             -> Maybe (Ref Window -> IO ()) -- ^ Optional table drawing routine
+             -> CustomWidgetFuncs Window    -- ^ Custom widget overrides
+             -> CustomWindowFuncs Window    -- ^ Custom window overrides
+             -> IO (Ref Window)
 windowCustom size position title draw' customWidgetFuncs' customWindowFuncs' =
   windowMaker
     size