haskell / haskell/deepseq

Documentation improvements

Open
#104 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
45
Forks
31
PR merge metrics
No merged PRs in 30d

Description

The "Generic NFData deriving" documentation section shows how to derive instances of both `NFData` and `NFData1` for `Foo`, but it doesn't say anything about when generic instances need `NFData1` (the `NFData1` documentation doesn't help either). As this is in the `NFData` class documentation, for people like me who first encountered `NFData` through a package that depends on it (Criterion in my case), this gives the impression that there must be a mysterious technicality that requires you to derive `NFData1` for types with a single type parameter whenever you need an `NFData` instance. This is what I thought until I experimented and found that `deepseq` works fine on your `Foo` example without the `NFData1` instance. E.g. in GHCi 8.10.7:

```haskell
λ: data Foo a = Foo a String deriving(Generic,NFData)
λ: (Foo undefined "Hello" :: Foo Int) `deepseq` 1
*** Exception: Prelude.undefined
```

I see from the source code that `rnf = rnf1` for functors like list, `Maybe` and `Either`, so I now wonder if `NFData1` and `NFData2` are just helper classes that are only useful when you're manually deriving `NFData` instances. Are there cases where `NFData` cannot be generically derived for unary/binary polymorphic types without `NFData1/2`? If not, can the derivation of `NFData1` be removed from the `Foo` examples, and can a note be added stating that generic instances do not require `NFData1/2`? Or if `NFData1/2` _does_ need to be generically derived sometimes, can someone add an explanation to the documentation?

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.