Document roles and Coercible related errors (#352)

Author: kl0tl

errors/DuplicateRoleDeclaration.md

@@ -0,0 +1,25 @@
+# `DuplicateRoleDeclaration` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+data D a = D a
+type role D nominal
+type role D nominal
+```
+
+## Cause
+
+Multiple role declarations are provided for the same type.
+
+## Fix
+
+- Remove the extraneous role declarations:
+
+```diff
+ data D a = D a
+ type role D nominal
+-type role D nominal
+```

errors/InvalidCoercibleInstanceDeclaration.md

@@ -0,0 +1,19 @@
+# `InvalidCoercibleInstanceDeclaration` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+import Prim.Coerce (class Coercible)
+
+instance coercible :: Coercible a b
+```
+
+## Cause
+
+`Coercible` instances are solved by the compiler and cannot be declared.
+
+## Fix
+
+- Remove the instance declaration.

errors/OrphanRoleDeclaration.md

@@ -0,0 +1,17 @@
+# `OrphanRoleDeclaration` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+type role D nominal
+```
+
+## Cause
+
+A role declaration is provided but does not immediately follow it's declaration.
+
+## Fix
+
+- Check that you've provided the appropriate `data` or `newtype` declaration.

errors/RoleDeclarationArityMismatch.md

@@ -0,0 +1,24 @@
+# `RoleDeclarationArityMismatch` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+data D a = D a
+type role D nominal nominal
+```
+
+## Cause
+
+The arity of a role declaration does not match the arity of its corresponding type.
+
+## Fix
+
+- Remove the extraneous roles:
+
+```diff
+ data D a = D a
+-type role D nominal nominal
++type role D nominal
+```

errors/RoleMismatch.md

@@ -0,0 +1,37 @@
+# `RoleMismatch` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+data D a = D a
+type role D phantom
+```
+
+```purescript
+module ShortFailingExample where
+
+data D f a = D (f a)
+type role D representational representational
+```
+
+## Cause
+
+A parameter was assigned a role more permissive than required.
+
+## Fix
+
+- Remove or strengthen the role declaration:
+
+```diff
+ data D a = D a
+-type role D phantom
++type role D representational
+```
+
+```diff
+ data D f a = D (f a)
+-type role D representational representational
++type role D representational nominal
+```

errors/UnsupportedRoleDeclaration.md

@@ -0,0 +1,35 @@
+# `UnsupportedRoleDeclaration` Error
+
+## Example
+
+```purescript
+module ShortFailingExample where
+
+class C a
+type role C representational
+```
+
+```purescript
+module ShortFailingExample where
+
+data D a = D a
+
+type S a = D a
+type role S nominal
+```
+
+## Cause
+
+A role declaration is provided for a type synonym or a type class.
+
+## Fix
+
+- Remove the role declaration or provide a role declaration for the underlying type of the synonym instead:
+
+```diff
+ data D a = D a
++type role D nominal
+ 
+ type S a = D a
+-type role S nominal
+```