Try to improve documentation

libraries/Graphics/Input/Field.elm

@@ -1,7 +1,8 @@
 module Graphics.Input.Field where
-{-| This library specifically addresses text fields. It uses the same general
-approach as the [`Graphics.Input`](Graphics-Input) module for describing an
-`Input`, so this library focuses on creating and styling text fields.
+{-| This library provides an API for creating and updating text fields.
+Text fields use exactly the same approach as [`Graphics.Input`](Graphics-Input)
+for modelling user input, allowing you to keep track of new events and update
+text fields programmatically.
 
 # Create Fields
 @docs field, password, email
@@ -20,21 +21,33 @@ import Graphics.Input (Input, Handle)
 import Native.Graphics.Input
 import Text
 
-{-| Easily create uniform dimensions:
+{-| Create uniform dimensions:
 
       uniformly 4 == { left=4, right=4, top=4, bottom=4 }
+
+The following example creates an outline where the left, right, top, and bottom
+edges all have width 1:
+
+      Outline grey (uniformly 1) 4
 -}
 uniformly : Int -> Dimensions
 uniformly n = Dimensions n n n n
 
 {-| For setting dimensions of a fields padding or border. The left, right, top,
-and bottom may all have different sizes.
+and bottom may all have different sizes. The following example creates
+dimensions such that the left and right are twice as wide as the top and bottom:
+
+      myDimensions : Int -> Dimensions
+      myDimensions n = { left = 2 * n, right = 2 * n, top = n, bottom = n }
 -}
 type Dimensions = { left:Int, right:Int, top:Int, bottom:Int }
 
 {-| A field can have a outline around it. This lets you set its color, width,
 and radius. The radius allows you to round the corners of your field. Set the
-width to zero to make it invisible.
+width to zero to make it invisible. Here is an example outline that is grey
+and thin with slightly rounded corners:
+
+      { color = grey, width = uniformly 1, radius = 4 }
 -}
 type Outline = { color:Color, width:Dimensions, radius:Int }
 
@@ -42,8 +55,12 @@ type Outline = { color:Color, width:Dimensions, radius:Int }
 noOutline : Outline
 noOutline = Outline Color.grey (uniformly 0) 0
 
-{-| When a field is selected, it has an highlight around it by default. Set the
-width of the `Highlight` to zero to make it go away.
+{-| When a field has focus, it has a blue highlight around it by default. The
+`Highlight` lets you set the `color` and `width` of this highlight. Set the
+`width` to zero to turn the highlight off. Here is an example highlight that
+is blue and thin:
+
+      { color = blue, width = 1 }
 -}
 type Highlight = { color:Color, width:Int }
 
@@ -51,10 +68,18 @@ type Highlight = { color:Color, width:Int }
 noHighlight : Highlight
 noHighlight = Highlight Color.blue 0
 
-{-| Describes the style of a text box. The `style` field describes the style
-of the text itself. The `outline` field describes the glowing blue outline that
-shows up when the field has focus. Turn off `outline` by setting its width to
-zero. The 
+{-| Describe the style of a text box. `style` describes the style of the text
+itself using [`Text.Style`](/Text#Style). `outline` describes the glowing blue
+outline that shows up when the field has focus. `outline` describes the line
+surrounding the text field, and `padding` adds whitespace between the `outline`
+and the text.
+
+The width and height of the text box *includes* the `padding` and `outline`.
+Say we have a text box that is 40 pixels tall. It has a uniform outline of
+1 pixel and a uniform padding of 5 pixels. Both of these must be subtracted
+from the total height to determine how much room there is for text. The
+`padding` and `outline` appear on the top and bottom, so there will be 28
+vertical pixels remaining for the text (40 - 1 - 5 - 5 - 1).
 -}
 type Style =
   { padding   : Dimensions
@@ -77,27 +102,32 @@ defaultStyle =
 
 {-| Represents the current content of a text field. For example:
 
-      Content "She sells sea shells" (Selection 0 3 Backward)
+      content = Content "She sells sea shells" (Selection 0 3 Backward)
 
-This means the user highlighted the substring `"She"` backwards.
+This means the user highlighted the substring `"She"` backwards. The value of
+`content.string` is `"She sells sea shells"`.
 -}
 type Content = { string:String, selection:Selection }
 
 {-| The selection within a text field. `start` is never greater than `end`:
 
-    Selection 0 0 Forward  -- cursor precedes all characters
+      Selection 0 0 Forward  -- cursor precedes all characters
 
-    Selection 5 9 Backward -- highlighting characters starting after
-                           -- the 5th and ending after the 9th
+      Selection 5 9 Backward -- highlighting characters starting after
+                             -- the 5th and ending after the 9th
 -}
 type Selection = { start:Int, end:Int, direction:Direction }
 
-{-| The direction of selection.-}
+{-| The direction of selection. When the user highlights a selection in a text
+field, they must do it in a particular direction. This determines which end of
+the selection moves when they change the selection by pressing Shift-Left or
+Shift-Right.
+-}
 data Direction = Forward | Backward
 
 {-| A field with no content:
 
-    Content "" (Selection 0 0 Forward)
+      Content "" (Selection 0 0 Forward)
 -}
 noContent : Content
 noContent = Content "" (Selection 0 0 Forward)