Convert Date, Mouse, Window, and Signal docs.

libraries/Date.elm

@@ -1,9 +1,17 @@
 
--- Library for working with dates. It is still a work in progress, so email
--- the mailing list if you are having issues with internationalization or
--- locale formatting or something.
 module Date where
 
+{-| Library for working with dates. Email the mailing list if you encounter
+issues with internationalization or locale formatting.
+
+# Conversions
+@docs read, toTime
+
+# Extractions
+@docs year, month, Month, day, dayOfWeek, Day, hour, minute, second
+
+-}
+
 import Basics (String)
 import Native.Date
 import Time (Time)
@@ -11,55 +19,55 @@ import Maybe (Maybe)
 
 data Date = Date
 
--- Represents the days of the week.
+{-| Represents the days of the week. -}
 data Day = Mon | Tue | Wed | Thu | Fri | Sat | Sun
 
--- Represents the month of the year.
+{-| Represents the month of the year. -}
 data Month = Jan | Feb | Mar | Apr
            | May | Jun | Jul | Aug
            | Sep | Oct | Nov | Dec
 
--- Attempt to read a date from a string.
+{-| Attempt to read a date from a string. -}
 read : String -> Maybe Date
 read = Native.Date.read
 
--- Convert a date into a time since midnight (UTC) of 1 January 1990 (i.e.
+{-| Convert a date into a time since midnight (UTC) of 1 January 1990 (i.e.
--- [UNIX time](http://en.wikipedia.org/wiki/Unix_time)). Given the date 23 June
+[UNIX time](http://en.wikipedia.org/wiki/Unix_time)). Given the date 23 June
--- 1990 at 11:45AM this returns the corresponding time.
+1990 at 11:45AM this returns the corresponding time. -}
 toTime : Date -> Time
 toTime = Native.Date.toTime
 
--- Extract the year of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the year of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the integer `1990`.
+this returns the integer `1990`. -}
 year : Date -> Int
 year = Native.Date.year
 
--- Extract the month of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the month of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the Month `Jun` as defined below.
+this returns the Month `Jun` as defined below. -}
 month : Date -> Month
 month = Native.Date.month
 
--- Extract the day of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the day of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the integer `23`.
+this returns the integer `23`. -}
 day : Date -> Int
 day = Native.Date.day
 
--- Extract the day of the week for a given date. Given the date 23 June
+{-| Extract the day of the week for a given date. Given the date 23 June
--- 1990 at 11:45AM this returns the Day `Thu` as defined below.
+1990 at 11:45AM this returns the Day `Thu` as defined below. -}
 dayOfWeek : Date -> Day
 dayOfWeek = Native.Date.dayOfWeek
 
--- Extract the hour of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the hour of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the integer `11`.
+this returns the integer `11`. -}
 hour : Date -> Int
 hour = Native.Date.hour
 
--- Extract the minute of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the minute of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the integer `45`.
+this returns the integer `45`. -}
 minute : Date -> Int
 minute = Native.Date.minute
 
--- Extract the second of a given date. Given the date 23 June 1990 at 11:45AM
+{-| Extract the second of a given date. Given the date 23 June 1990 at 11:45AM
--- this returns the integer `0`.
+this returns the integer `0`. -}
 second : Date -> Int
-second = Native.Date.second
+second = Native.Date.second

libraries/Mouse.elm

@@ -1,31 +1,41 @@
 
 module Mouse where
 
+{-| Library for working with mouse input.
+
+# Position
+@docs position, x, y
+
+# Button Status
+@docs isDown, clicks, isClicked
+
+-}
+
 import Signal (Signal)
 import Native.Mouse
 
--- The current mouse position.
+{-| The current mouse position. -}
 position : Signal (Int,Int)
 position = Native.Mouse.position
 
--- The current x-coordinate of the mouse.
+{-| The current x-coordinate of the mouse. -}
 x : Signal Int
 x = Native.Mouse.x
 
--- The current y-coordinate of the mouse.
+{-| The current y-coordinate of the mouse. -}
 y : Signal Int
 y = Native.Mouse.y
 
--- The current state of the left mouse-button.
+{-| The current state of the left mouse-button.
--- True when the button is down, and false otherwise.
+True when the button is down, and false otherwise. -}
 isDown : Signal Bool
 isDown = Native.Mouse.isDown
 
--- True immediately after the left mouse-button has been clicked,
+{-| True immediately after the left mouse-button has been clicked,
--- and false otherwise.
+and false otherwise. -}
 isClicked : Signal Bool
 isClicked = Native.Mouse.isClicked
 
--- Always equal to unit. Event triggers on every mouse click.
+{-| Always equal to unit. Event triggers on every mouse click. -}
 clicks : Signal ()
-clicks = Native.Mouse.clicks
+clicks = Native.Mouse.clicks

libraries/Signal.elm

@@ -1,32 +1,52 @@
 
--- The library for general signal manipulation. Some useful functions for
+{-| The library for general signal manipulation. Includes lift functions up to
--- working with time (e.g. setting FPS) and combining signals and time (e.g.
+`lift8` and infix lift operators `<~` and `~`, combinations, filters, and
--- delaying updates, getting timestamps) can be found in the
+past-dependence.
--- [`Time`](/docs/Signal/Time.elm) library.
+
---
+Signals are time-varying values. Lifted functions are reevaluated whenver any of
--- Note: There are lift functions up to `lift8`.
+their input signals has an event. Signal events may be of the same value as the
+previous value of the signal. Such signals are useful for timing and
+past-dependence.
+
+Some useful functions for working with time (e.g. setting FPS) and combining
+signals and time (e.g.  delaying updates, getting timestamps) can be found in
+the [`Time`](/docs/Signal/Time.elm) library.
+
+# Combine
+@docs constant, lift, lift2, merge, merges, combine
+
+# Pretty Lift
+@docs (<~), (~)
+
+# Past-Dependence
+@docs foldp, count, countIf
+
+#Filters
+@docs keepIf, dropIf, keepWhen, dropWhen, dropRepeats, sampleOn
+
+# Do you even lift?
+@docs lift3, lift4, lift5, lift6, lift7, lift8
+
+-}
 module Signal where
 
 import Native.Signal
 import List (foldr)
 
 data Signal a = Signal
---    = Constant a
---    | Lift (a -> a) (Signal a)
 
--- Create a constant signal that never changes.
+{-| Create a constant signal that never changes. -}
 constant : a -> Signal a
 constant = Native.Signal.constant
 
--- Transform a signal with a given function.
+{-| Transform a signal with a given function. -}
 lift  : (a -> b) -> Signal a -> Signal b
 lift = Native.Signal.lift
 
--- Combine two signals with a given function.
+{-| Combine two signals with a given function. -}
 lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
 lift2 = Native.Signal.lift2
 
--- Combine three signals with a given function.
 lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
 lift3 = Native.Signal.lift3
 
@@ -49,25 +69,25 @@ lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
 lift8 = Native.Signal.lift8
 
 
--- Create a past-dependent signal. Each value given on the input signal will
+{-| Create a past-dependent signal. Each value given on the input signal will
--- be accumulated, producing a new output value.
+be accumulated, producing a new output value.
---
+
--- For instance, `(foldp (\\arrows number -> number + arrows.y) 0 Keyboard.arrows)`
+For instance, `foldp (+) 0 (fps 40)` is the time the program has been running,
--- increments or decrements the accumulated value (which starts at zero) when the up or down arrow keys are pressed.
+updated 40 times a second. -}
 foldp : (a -> b -> b) -> b -> Signal a -> Signal b
 foldp = Native.Signal.foldp
 
--- Merge two signals into one, biased towards the first signal if both signals
+{-| Merge two signals into one, biased towards the first signal if both signals
--- update at the same time.
+update at the same time. -}
 merge : Signal a -> Signal a -> Signal a
 merge = Native.Signal.merge
 
--- Merge many signals into one, biased towards the left-most signal if multiple
+{-| Merge many signals into one, biased towards the left-most signal if multiple
--- signals update simultaneously.
+signals update simultaneously. -}
 merges : [Signal a] -> Signal a
 merges = Native.Signal.merges
 
--- Combine a list of signals into a signal of lists.
+{-| Combine a list of signals into a signal of lists. -}
 combine : [Signal a] -> Signal [a]
 combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
 
@@ -76,70 +96,74 @@ combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
  -- fold over non-homogeneous inputs.
  -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
 
--- Count the number of events that have occured.
+{-| Count the number of events that have occured. -}
 count : Signal a -> Signal Int
 count = Native.Signal.count
 
--- Count the number of events that have occured that satisfy a given predicate.
+{-| Count the number of events that have occured that satisfy a given predicate.
+-}
 countIf : (a -> Bool) -> Signal a -> Signal Int
 countIf = Native.Signal.countIf
 
--- Keep only events that satisfy the given predicate. Elm does not allow
+{-| Keep only events that satisfy the given predicate. Elm does not allow
--- undefined signals, so a base case must be provided in case the predicate is
+undefined signals, so a base case must be provided in case the predicate is
--- never satisfied.
+never satisfied. -}
 keepIf : (a -> Bool) -> a -> Signal a -> Signal a
 keepIf = Native.Signal.keepIf
 
--- Drop events that satisfy the given predicate. Elm does not allow undefined
+{-| Drop events that satisfy the given predicate. Elm does not allow undefined
--- signals, so a base case must be provided in case the predicate is never
+signals, so a base case must be provided in case the predicate is never
--- satisfied.
+satisfied. -}
 dropIf : (a -> Bool) -> a -> Signal a -> Signal a
 dropIf = Native.Signal.dropIf
 
--- Keep events only when the first signal is true. When the first signal becomes
+{-| Keep events only when the first signal is true. When the first signal
--- true, the most recent value of the second signal will be propagated. Until
+becomes true, the most recent value of the second signal will be propagated.
--- the first signal becomes false again, all events will be propagated. Elm does
+Until the first signal becomes false again, all events will be propagated. Elm
--- not allow undefined signals, so a base case must be provided in case the first
+does not allow undefined signals, so a base case must be provided in case the
--- signal is never true.
+first signal is never true. -}
 keepWhen : Signal Bool -> a -> Signal a -> Signal a
 keepWhen = Native.Signal.keepWhen
 
--- Drop events when the first signal is true. When the first signal becomes false,
+{-| Drop events when the first signal is true. When the first signal becomes
--- the most recent value of the second signal will be propagated. Until the first
+false, the most recent value of the second signal will be propagated. Until the
--- signal becomes true again, all events will be propagated. Elm does not allow
+first signal becomes true again, all events will be propagated. Elm does not
--- undefined signals, so a base case must be provided in case the first signal is
+allow undefined signals, so a base case must be provided in case the first
--- always true.
+signal is always true. -}
 dropWhen : Signal Bool -> a -> Signal a -> Signal a
 dropWhen = Native.Signal.dropWhen
 
--- Drop sequential repeated values. For example, if a signal produces the
+{-| Drop sequential repeated values. For example, if a signal produces the
--- sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that
+sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that are the
--- are the same as the previous value.
+same as the previous value. -}
 dropRepeats : Signal a -> Signal a
 dropRepeats = Native.Signal.dropRepeats
 
--- Sample from the second input every time an event occurs on the first input.
+{-| Sample from the second input every time an event occurs on the first input.
--- For example, `(sampleOn clicks (every second))` will give the approximate
+For example, `(sampleOn clicks (every second))` will give the approximate time
--- time of the latest click.
+of the latest click. -}
 sampleOn : Signal a -> Signal b -> Signal b
 sampleOn = Native.Signal.sampleOn
 
--- An alias for `lift`. A prettier way to apply a
+{-| An alias for `lift`. A prettier way to apply a function to the current value
--- function to the current value of a signal.
+of a signal. -}
---
---         lift f signal == f <~ signal
 (<~) : (a -> b) -> Signal a -> Signal b
 f <~ s = Native.Signal.lift f s
 
--- Signal application. This takes two signals, holding a function and
+{-| Informally, an alias for `liftN`. Intersperse it between additional signal
--- a value. It applies the current function to the current value.
+arguments of the lifted function.
---
+
--- So the following expressions are equivalent:
+Formally, signal application. This takes two signals, holding a function and
---
+a value. It applies the current function to the current value.
---         scene <~ Window.dimensions ~ Mouse.position
+
---         lift2 scene Window.dimensions Mouse.position
+The following expressions are equivalent:
+
+         scene <~ Window.dimensions ~ Mouse.position
+         lift2 scene Window.dimensions Mouse.position
+-}
+
 (~) : Signal (a -> b) -> Signal a -> Signal b
 sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
 
 infixl 4 <~
-infixl 4 ~
+infixl 4 ~

libraries/Window.elm

@@ -1,18 +1,27 @@
 
 module Window where
 
+{-| Provides information about the container that your Elm program lives in.
+When you embed Elm in a `<div>` it gives the dimensions of the container, not
+the whole window.
+
+# Dimensions
+@docs dimensions, width, height
+
+-}
+
 import Signal (Signal)
 import Native.Window
 
--- The current dimensions of the window (i.e. the area viewable to the
+{-| The current width and height of the window (i.e. the area viewable to the
--- user, not including scroll bars).
+user, not including scroll bars). -}
 dimensions : Signal (Int,Int)
 dimensions = Native.Window.dimensions
 
--- The current width of the window.
+{-| The current width of the window. -}
 width : Signal Int
 width = Native.Window.width
 
--- The current height of the window.
+{-| The current height of the window. -}
 height : Signal Int
 height = Native.Window.height