Documentation cleanup.

Also, deprecate the hue, saturation, luminosity, and alpha
functions.  These properties can be extracted by pattern
matching, and there's no pedagogical need to use them earlier
in the learning process.

Author: cdsmith

codeworld-base/src/Internal/CodeWorld.hs

@@ -54,21 +54,83 @@ instance Show LiteralException where
 traced :: (a, CWT.Text) -> a
 traced (x, msg) = CW.trace (CWT.fromCWText msg) x
 
+-- | A computer program.
+--
+-- This is a specific task or application that a computer performs.  In
+-- CodeWorld, programs are defined using one of the "entry point"
+-- functions, such as 'drawingOf', 'animationOf', or 'activityOf'.
 type Program = IO ()
 
+-- | A program that displays a drawing of a single picture.
+--
+-- This is the simplest way to define a program in CodeWorld.  The
+-- argument is a 'Picture'.
+--
+-- For example:
+-- 
+-- > program = drawingOf(codeWorldLogo)
 drawingOf :: Picture -> Program
 drawingOf pic = CW.drawingOf (toCWPic pic) `catch` reportError
 
+-- | A program that shows an animation changing over time.
+--
+-- The argument is a function, which maps each time (a 'Number' in
+-- seconds since the program started) to the 'Picture' that is shown
+-- at that time.
+--
+-- For example:
+-- 
+-- > program = animationOf(f)
+-- > f(t) = rotated(rectangle(5,5), 45 * t)
 animationOf :: (Number -> Picture) -> Program
 animationOf f = CW.animationOf (toCWPic . f . fromDouble) `catch` reportError
 
+-- | A program that can interact with a user by responding to pointer
+-- and keyboard events and remember state.
+--
+-- To create an activity, you first choose a type for its state,
+-- called the "world" type.  You will then describe the activity
+-- with three arguments:
+--
+-- 1. A function to create an initial world.  The argument to
+--    this function is an infinite sequence of random numbers,
+--    which you can use to create a randomly chosen world.
+-- 2. A function that describes how the world changes when
+--    things happen.  The function receives an old world and
+--    an 'Event' that occurs, and maps it to a new world.
+-- 3. A function that converts a world into a 'Picture', used
+--    to display the program on the screen.
+--
+-- For example:
+--
+-- > program = activityOf(initial, change, picture)
+-- >
+-- > initial(rs) = 0
+-- >
+-- > change(x, KeyPress("A")) = x - 1
+-- > change(x, KeyPress("D")) = x + 1
+-- > change(x, other) = x
+-- >
+-- > picture(x) = translated(solidCircle(1), x, 0)
+--
+-- In mathematical language, an activity is called a dynamical
+-- system.  The world type is known as the phase space of the
+-- system, and the @change@ function is called the dynamics of
+-- the system.  The @initial@ and @picture@ functions are not
+-- part of the system, but describe how the program should
+-- simulate and display it.
 activityOf ::
        ( [Number] -> world
        , (world, Event) -> world
        , world -> Picture)
     -> Program
 activityOf (initial, event, draw) = interactionOf (initial, fst, event, draw)
 
+-- | A program that acts just like one built with 'activityOf',
+-- but offers more tools to pause, rewind, and otherwise
+-- understand the program behavior.  This can be used during
+-- development, and then changed back to 'activityOf' once the
+-- program is complete.
 debugActivityOf ::
        ( [Number] -> world
        , (world, Event) -> world
@@ -77,6 +139,23 @@ debugActivityOf ::
 debugActivityOf (initial, event, draw) =
     debugInteractionOf (initial, fst, event, draw)
 
+-- | A program that interacts with multiple different users by
+-- responding to their pointer and keyboard events.
+--
+-- The arguments to this function are similar 'activityOf',
+-- except that:
+--
+-- 1. A first argument, a 'Number' gives the desired number of
+--    players.
+-- 2. The @change@ function receives an extra argument telling
+--    which player intiated the event.
+-- 3. The @picture@ function receives an extra argument with
+--    the player for whom the picture should be built.
+--
+-- The activity will always begin with a "lobby", where players
+-- can create new games or join existing games with a code.
+-- Once the desired number of players have joined, the activity
+-- will begin.
 groupActivityOf ::
        ( Number
        , [Number] -> state

codeworld-base/src/Internal/Color.hs

@@ -27,7 +27,25 @@ import Internal.Truth
 import qualified "base" Prelude as P
 import "base" Prelude ((.))
 
+-- | A color.
+--
+-- Colors can be described in several ways:
+--
+-- 1. Using common color names: 'red', 'blue', 'yellow', 'green',
+--    'orange', 'purple', 'pink', 'black', 'white', 'brown', and
+--    'gray'.
+-- 2. Transforming other colors with functions such as 'light',
+--    'dark', 'bright', 'dull', 'translucent', and 'mixed'.
+-- 3. Constructing colors from coordinates in a color space, such
+--    as 'RGB', 'RGBA', or 'HSL'.
+--
+-- Note that transparency is included in a color.  Common color
+-- names and the 'RGB' and 'HSL' constructors only produce opaque
+-- colors, but 'RGBA' and the 'translucent' function work with
+-- transparency.
 newtype Color = Color { toCWColor :: CW.Color } deriving (P.Eq)
+
+-- | A synonym for 'Color', using the non-US spelling.
 type Colour = Color
 
 {-# RULES
@@ -72,36 +90,95 @@ fromHSL :: (Number, Number, Number) -> Color
 fromHSL (h, s, l) =
     Color (CW.HSL (toDouble (pi * h / 180)) (toDouble s) (toDouble l))
 
+-- | Produces a color by mixing other colors in equal proportion.
+--
+-- The order of colors is unimportant.  Colors may be mixed in uneven
+-- proportions by listing a color more than once, such as
+-- @mixed([red, red, orange])@.
 mixed :: [Color] -> Color
 mixed = Color . CW.mixed . P.map toCWColor
 
+-- | Increases the luminosity of a color by the given amount.
+--
+-- The amount should be between -1 and 1, where:
+--
+-- * @lighter(c, 1)@ is always white, regardless of @c@.
+-- * @lighter(c, 0)@ is the same as @c@.
+-- * @lighter(c, -1)@ is always black, regardless of @c@.
 lighter :: (Color, Number) -> Color
 lighter (c, d) = Color (CW.lighter (toDouble d) (toCWColor c))
 
+-- | Produces a lighter shade of the given color.
+--
+-- This function may be nested more than once to produce an even
+-- lighter shade, as in @light(light(blue))@.
 light :: Color -> Color
 light = Color . CW.light . toCWColor
 
+-- | Decreases the luminosity of a color by the given amount.
+--
+-- The amount should be between -1 and 1, where:
+--
+-- * @darker(c, 1)@ is always black, regardless of @c@.
+-- * @darker(c, 0)@ is the same as @c@.
+-- * @darker(c, -1)@ is always white, regardless of @c@.
 darker :: (Color, Number) -> Color
 darker (c, d) = Color (CW.darker (toDouble d) (toCWColor c))
 
+-- | Produces a darker shade of the given color.
+--
+-- This function may be nested more than once to produce an even
+-- darker shade, as in @dark(dark(green))@.
 dark :: Color -> Color
 dark = Color . CW.dark . toCWColor
 
+-- | Increases the saturation of a color by the given amount.
+--
+-- The amount should be between -1 and 1, where:
+--
+-- * @brighter(c, 1)@ is a fully saturated version of @c@.
+-- * @brighter(c, 0)@ is the same as @c@.
+-- * @brighter(c, -1)@ is just a shade of gray with no color.
 brighter :: (Color, Number) -> Color
 brighter (c, d) = Color (CW.brighter (toDouble d) (toCWColor c))
 
+-- | Produces a brighter shade of the given color; that is, less
+-- gray and more colorful.
+--
+-- This function may be nested more than once to produce an even
+-- brighter shade, as in @bright(bright(yellow))@.
 bright :: Color -> Color
 bright = Color . CW.bright . toCWColor
 
+-- | Decreases the saturation of a color by the given amount.
+--
+-- The amount should be between -1 and 1, where:
+--
+-- * @duller(c, 1)@ is just a shade of gray with no color.
+-- * @duller(c, 0)@ is the same as @c@.
+-- * @duller(c, -1)@ is a fully saturated version of @c@.
 duller :: (Color, Number) -> Color
 duller (c, d) = Color (CW.duller (toDouble d) (toCWColor c))
 
+-- | Produces a duller shade of the given color; that is, more
+-- gray and less colorful.
+--
+-- This function may be nested more than once to produce an even
+-- duller shade, as in @dull(dull(purple))@.
 dull :: Color -> Color
 dull = Color . CW.dull . toCWColor
 
+-- | Produces a partially transparent color.
+--
+-- This function may be nested more than once to produce an even
+-- more transparent color, as in @translucent(translucent(brown))@.
 translucent :: Color -> Color
 translucent = Color . CW.translucent . toCWColor
 
+-- | An infinite list of various colors.
+--
+-- The list is chosen to contain a variety of different hues as
+-- spread out as possible to create colorful effects.
 assortedColors :: [Color]
 assortedColors = P.map Color CW.assortedColors
 
@@ -116,32 +193,65 @@ alpha = fromDouble . CW.alpha . toCWColor
 
 -- New style colors
 
--- Old style colors
-
-white, black, red, green, blue, cyan, magenta, yellow :: Color
-orange, rose, chartreuse, aquamarine, violet, azure :: Color
-gray, grey :: Color
-
+-- | The color white
+white :: Color
 white  = Color CW.white
+
+-- | The color black
+black :: Color
 black  = Color CW.black
+
+-- | The color gray
+gray :: Color
 gray   = Color CW.gray
+
+-- | The color grey
+--
+-- This is the same color as 'gray', but with a non-US
+-- spelling.
+grey :: Color
 grey   = Color CW.grey
+
+-- | The color red
+red :: Color
 red    = Color CW.red
+
+-- | The color orange
+orange :: Color
 orange = Color CW.orange
+
+-- | The color yellow
+yellow :: Color
 yellow = Color CW.yellow
+
+-- | The color green
+green :: Color
 green  = Color CW.green
+
+-- | The color blue
+blue :: Color
 blue   = Color CW.blue
+
+-- | The color purple
+purple :: Color
 purple = Color CW.purple
+
+-- | The color pink
+pink :: Color
 pink   = Color CW.pink
+
+-- | The color brown
+brown :: Color
 brown  = Color CW.brown
 
+cyan, magenta, rose, chartreuse, aquamarine, violet, azure :: Color
 cyan = Color CW.cyan
 magenta = Color CW.magenta
+rose = Color CW.rose
 chartreuse = Color CW.chartreuse
 aquamarine = Color CW.aquamarine
-azure = Color CW.azure
 violet = Color CW.violet
-rose = Color CW.rose
+azure = Color CW.azure
 
 {-# WARNING magenta    [ "Please use HSL(300, 0.75, 0.5) instead of magenta."
                        , "The variable magenta may be removed July 2020." ] #-}
@@ -157,3 +267,11 @@ rose = Color CW.rose
                        , "The variable rose may be removed July 2020." ] #-}
 {-# WARNING violet     [ "Please use purple instead of violet."
                        , "The variable violet may be removed July 2020." ] #-}
+{-# WARNING hue        [ "Please match HSL(...) instead of using hue(...)."
+                       , "The hue function may be removed July 2020." ] #-}
+{-# WARNING saturation [ "Please match HSL(...) instead of using saturation(...)."
+                       , "The saturation function may be removed July 2020." ] #-}
+{-# WARNING luminosity [ "Please match HSL(...) instead of using luminosity(...)."
+                       , "The luminosity function may be removed July 2020." ] #-}
+{-# WARNING alpha      [ "Please match RGBA(...) instead of using alpha(...)."
+                       , "The alpha function may be removed July 2020." ] #-}