copilot-core: Warn about future generic default for updateField. Refs #564.

Currently, using structs in Copilot requires defining instances of several type
classes. Defining those instances is unnecessarily cumbersome, and it exposes
the user to a substantial amount of Haskell even when they want to stay at the
level of the Copilot language.

In the previous commit, we added `Generic`-based defaults for several type
class methods, including the `updateField` method of `Struct`.

In the future, we plan to change the default implementation for `updateField`
such that it will require a `Generic` instance. This will break any existing
`Struct` instance that omits an implementation of `updateField` and also does
not define a `Generic` instance for the struct data type. Unfortunately, there
does not appear to be a way for GHC to warn about this combination of
properties.

This commit adds a verbal warning to the `updateField` Haddocks to make users
aware of this potential problem.

Author: RyanGlScott

copilot-core/src/Copilot/Core/Type.hs

@@ -70,24 +70,35 @@ class Struct a where
   toValues :: a -> [Value a]
 
   -- | Update the value of a struct field. This is only used by the Copilot
-  -- interpreter, so if you do not plan to use the interpreter, it is safe to
-  -- omit an implementation of this method.
+  -- interpreter.
   --
-  -- In order to implement 'updateField', you should do the following for each
-  -- 'Field' in a struct:
+  -- If you do not plan to use the interpreter, you can omit an implementation
+  -- of this method. If you do so, it is recommended that you derive a 'Generic'
+  -- instance for the struct data type. This is because in a future release, the
+  -- default implementation of 'updateField' (which will be picked if there is
+  -- not a manually written implementation) will be changed to require a
+  -- 'Generic' instance.
   --
-  -- 1. Check that the name of the 'Field' matches the name of the supplied
-  --    'Value' (using 'GHC.TypeLits.sameSymbol').
+  -- In order to implement 'updateField', pick one of the following approaches:
   --
-  -- 2. Check that the type of the 'Field' matches the 'Type' of the supplied
-  --    'Value' (using 'DE.testEquality').
+  -- * Derive a 'Generic' instance for the struct data type and then define
+  --   @'updateField' = 'updateFieldDefault'@ in the 'Struct' instance.
   --
-  -- 3. If both (1) and (2) succeed, update the corresponding struct field using
-  --    a record update.
+  -- * Manually implement 'updateField' by doing the following for each 'Field'
+  --   in a struct:
   --
-  -- For a complete end-to-end example that demonstrates how to implement
-  -- 'updateField' and use it in the Copilot interpreter, see the
-  -- @examples/StructsUpdateField.hs@ example in the @copilot@ library.
+  --   1. Check that the name of the 'Field' matches the name of the supplied
+  --      'Value' (using 'GHC.TypeLits.sameSymbol').
+  --
+  --   2. Check that the type of the 'Field' matches the 'Type' of the supplied
+  --      'Value' (using 'DE.testEquality').
+  --
+  --   3. If both (1) and (2) succeed, update the corresponding struct field
+  --      using a record update.
+  --
+  --   For a complete end-to-end example that demonstrates how to manually
+  --   implement 'updateField' and use it in the Copilot interpreter, see the
+  --   @examples/StructsUpdateField.hs@ example in the @copilot@ library.
   updateField :: a -> Value t -> a
   updateField = error $ unlines
     [ "Field updates not supported for this type."