deepseq icon indicating copy to clipboard operation
deepseq copied to clipboard

Documentation improvements

Open OsePedro opened this issue 6 months ago • 4 comments

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:

λ: 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?

OsePedro avatar Aug 06 '24 18:08 OsePedro