Merge pull request #385 from haskell/mpj/comments-and-changelog

Add a few comments and tweaks to dependent-sum replacements

Author: michaelpj

lsp-types/src/Language/LSP/Types/Method.hs

@@ -188,24 +188,38 @@ data SMethod (m :: Method f t) where
   SCancelRequest                      :: SMethod CancelRequest
   SCustomMethod                       :: Text -> SMethod CustomMethod
 
+-- This instance is written manually rather than derived to avoid a dependency
+-- on 'dependent-sum-template'.
 instance GEq SMethod where
   geq x y = case gcompare x y of
     GLT -> Nothing
     GEQ -> Just Refl
     GGT -> Nothing
 
+-- This instance is written manually rather than derived to avoid a dependency
+-- on 'dependent-sum-template'.
 instance GCompare SMethod where
   gcompare (SCustomMethod x) (SCustomMethod y) = case x `compare` y of
     LT -> GLT
     EQ -> GEQ
     GT -> GGT
+  -- This is much more compact than matching on every pair of constructors, which
+  -- is what we would need to do for GHC to 'see' that this is correct. Nonetheless
+  -- it is safe: since there is only one constructor of 'SMethod' for each 'Method',
+  -- the argument types can only be equal if the constructor tag is equal.
   gcompare x y = case I# (dataToTag# x) `compare` I# (dataToTag# y) of
     LT -> GLT
     EQ -> unsafeCoerce GEQ
     GT -> GGT
 
-deriving instance Eq   (SMethod m)
-deriving instance Ord  (SMethod m)
+instance Eq (SMethod m) where
+  -- This defers to 'GEq', ensuring that this version is compatible.
+  (==) = defaultEq
+
+instance Ord (SMethod m) where
+  -- This defers to 'GCompare', ensuring that this version is compatible.
+  compare = defaultCompare
+
 deriving instance Show (SMethod m)
 
 -- Some useful type synonyms

lsp-types/src/Language/LSP/Types/SMethodMap.hs

@@ -21,13 +21,22 @@ import Data.Kind (Type)
 import Data.Map (Map)
 import qualified Data.Map.Strict as Map
 import Data.Text (Text)
-import GHC.Exts (Int(..), dataToTag#)
+import GHC.Exts (Int(..), dataToTag#, Any)
 import Unsafe.Coerce (unsafeCoerce)
 
 import Language.LSP.Types.Method (Method(..), SMethod(..))
 
+-- This type exists to avoid a dependency on 'dependent-map'. It is less
+-- safe (since we use 'unsafeCoerce') but much simpler and hence easier to include.
+-- | A specialized altenative to a full dependent map for use with 'SMethod'.
 data SMethodMap (v :: Method f t -> Type) =
-  SMethodMap !(IntMap (v 'CustomMethod)) !(Map Text (v 'CustomMethod))
+  -- This works by using an 'IntMap' indexed by constructor tag for the majority
+  -- of 'SMethod's, which have no parameters, and hence can only appear once as keys
+  -- in the map. We do not attempt to be truly dependent here, and instead exploit
+  -- 'usafeCoerce' to go to and from 'v Any'.
+  -- The sole exception is 'SCustomMethod', for which we keep a separate map from
+  -- its 'Text' parameter (and where we can get the type indices right).
+  SMethodMap !(IntMap (v Any)) !(Map Text (v 'CustomMethod))
 
 toIx :: SMethod a -> Int
 toIx k = I# (dataToTag# k)