Add more documentation

libraries/Text.elm

@@ -1,15 +1,21 @@
 module Text where
-
+{-| A library for styling and displaying text. Whlie the `String` library
-{-| Functions for displaying text
+focuses on representing and manipulating strings of character strings, the
+`Text` library focuses on how those strings should look on screen. It lets
+you make text bold or italic, set the typeface, set the text size, etc.
 
 # Creating Text
 @docs toText
 
 # Creating Elements
+
+Each of the following functions places `Text` into a box. The function you use
+determines the alignment of the text.
+
 @docs leftAligned, rightAligned, centered, justified
 
 # Links and Style
-@docs link, Style, style, Line, defaultStyle
+@docs link, Style, style, defaultStyle, Line
 
 # Convenience Functions
 
@@ -35,9 +41,28 @@ import Native.Text
 
 data Text = Text
 
+{-| Styles for lines on text. This allows you to add an underline, an overline,
+or a strike out text:
+
+      line Under   (toText "underline")
+      line Over    (toText "overline")
+      line Through (toText "strike out")
+-}
 data Line = Under | Over | Through
 
-{-| Representation of all the ways you can style `Text`.
+{-| Representation of all the ways you can style `Text`. If the `typeface` list
+is empty or the `height` is `Nothing`, the users will fall back on their
+browser's default settings. The following `Style` is black, 16 pixel tall,
+underlined, and Times New Roman (assuming that typeface is available on the
+user's computer):
+
+      { typeface = [ "Times New Roman", "serif" ]
+      , height   = Just 16
+      , color    = black
+      , bold     = False
+      , italic   = False
+      , line     = Just Under
+      }
 -}
 type Style =
   { typeface : [String]
@@ -69,11 +94,19 @@ defaultStyle =
   , line = Nothing
   }
 
-{-| Convert a string into text which can be styled and displayed. -}
+{-| Convert a string into text which can be styled and displayed. To show the
+string `"Hello World!"` on screen in italics, you could say:
+
+      main = leftAligned (italic (toText "Hello World!"))
+-}
 toText : String -> Text
 toText = Native.Text.toText
 
-{-| Set the style of some text.
+{-| Set the style of some text. For example, if you design a `Style` called
+`footerStyle` that is specifically for the bottom of your page, you could apply
+it to text like this:
+
+      style footerStyle (toText "the old prince / 2007")
 -}
 style : Style -> Text -> Text
 style = Native.Text.style
@@ -82,53 +115,93 @@ style = Native.Text.style
 
       ["helvetica","arial","sans-serif"]
 
-Not everyone has access to the same typefaces, so rendering will use the first
+Not every browser has access to the same typefaces, so rendering will use the
-typeface in the list that is found on the user's computer. If there are no
+first typeface in the list that is found on the user's computer. If there are
-matches, it will use their default typeface. Works the same as the CSS
+no matches, it will use their default typeface. This works the same as the CSS
 font-family property.
 -}
 typeface : [String] -> Text -> Text
 typeface = Native.Text.typeface
 
-{-| Switch to a monospace typeface. Good for code snippets. -}
+{-| Switch to a monospace typeface. Good for code snippets.
+
+      monospace (toText "foldl (+) 0 [1,2,3]")
+-}
 monospace : Text -> Text
 monospace = Native.Text.monospace
 
-{-| Create a link.
+{-| Create a link by providing a URL and the text of the link:
 
       link "http://elm-lang.org" (toText "Elm Website")
 -}
 link : String -> Text -> Text
 link = Native.Text.link
 
+{-| Set the height of some text:
+
+      height 40 (toText "Title")
+-}
 height : Float -> Text -> Text
 height = Native.Text.height
 
+{-| Set the color of some text:
+
+      color red (toText "Red")
+-}
 color : Color -> Text -> Text
 color = Native.Text.color
 
+{-| Make text bold:
+
+      toText "sometimes you want " ++ bold (toText "emphasis")
+-}
 bold : Text -> Text
 bold = Native.Text.bold
 
+{-| Make text italic:
+
+      toText "make it " ++ italic (toText "important")
+-}
 italic : Text -> Text
 italic = Native.Text.italic
 
+{-| Put lines on text:
+
+      line Under   (toText "underlined")
+      line Over    (toText "overlined")
+      line Through (toText "strike out")
+-}
 line : Line -> Text -> Text
 line = Native.Text.line
 
+{-| `Text` is aligned along the left side of the text block. This is sometimes
+known as *ragged right*.
+-}
 leftAligned : Text -> Element
 leftAligned = Native.Text.leftAligned
 
+{-| `Text` is aligned along the right side of the text block. This is sometimes
+known as *ragged left*.
+-}
 rightAligned : Text -> Element
 rightAligned = Native.Text.rightAligned
 
+{-| `Text` is centered in the text block. There is equal spacing on either side
+of a line of text.
+-}
 centered : Text -> Element
 centered = Native.Text.centered
 
+{-| `Text` is aligned along the left and right sides of the text block. Word
+spacing is adjusted to make this possible.
+-}
 justified : Text -> Element
 justified = Native.Text.justified
 
-{-| Display a plain string. -}
+{-| Display a string with no styling:
+
+      plainText string = leftAligned (toText string)
+-}
 plainText : String -> Element
 plainText str =
     leftAligned (toText str)
@@ -140,7 +213,7 @@ markdown = Native.Text.markdown
 {-| Convert anything to its textual representation and make it displayable in
 the browser:
 
-        asText == text . monospace . show
+        asText value = text (monospace (show value))
 
 Excellent for debugging.
 -}