Repository navigation
Add content on derriving instances in Ch6 #149
Description
Activity
@milesfrain Per our discussion in PR #146, an explanatory comment has been added via commit 678fe4a for the solutions branch and commit 93117cb for the master branch; this takes care of the Ch7 exercise issue.
Hence, this buys us a bit of time for adding content to Ch6.
Both
derivein thedatacase should be give and alsoderive newtype. I haven't checked the docs in a long while, but even in the docs at the timederive newtypewas brushed over.I helped clarify this entry from Jordan's notes https://github.com/JordanMartinez/purescript-jordans-reference/blob/c47db1aa2221c8874bfe4ff67eab2c01d6d6bcf9/11-Syntax/01-Basic-Syntax/src/09-Newtypes/22-Deriving-Typeclass-Instances-for-Newtyped-Types.purs which in essence is pretty simple to understand I think, as long as there are a couple of examples provided.
There's a pending PR to add more deriving details to the docs. purescript/documentation#338
Here's the most complete version.
https://github.com/purescript/documentation/blob/66fcdc26b48ed42002ae36d63699ef55494f0afd/language/Type-Classes.md#type-class-derivingHowever, the info on deriving from generic and avoiding stack overflows won't be included. Considering adding those to the generics-rep docs instead. https://github.com/purescript/purescript-generics-rep/issues/41
So it looks like we'll have documentation on
deriveduplicated in a few locations:- Docs repo
- Jordan's reference
- This book
generics-replibrary
Ideally, we'd have documentation for a topic in one location that we can then link to from the other locations. Not sure what our long-term plan is for organizing these docs.
As an outsider perspective. Projects seem to organize official docs and tutorials. Purescript and Rust are the only projects I know that have a dedicated official book.
So I think it makes sense that either the book or the official docs should be "the primary source" everything else should link to.
I'd see the book as a medium to explore through examples and possibly real-world cases the official docs, even if it's an official book. So perhaps it should also link to the official docs as well.
Also usually the official docs are the ones kept up to date as books need more time to rewrite based on how the examples presented are more or less complex, exercises and solutions adapted, etc.
I'd see the book as a medium to explore through examples and possibly real-world cases the official docs, even if it's an official book. So perhaps it should also link to the official docs as well.
That sounds good to me. Ideally, I'd like the book to focus on providing:
- Suggested sequence of topics to learn
- Exercises to check your understanding
- Some glue explanations to connect multiple topics
- Exercises / Projects that combine the previously-learned material
This would involve the book linking to common docs whenever possible.
Some concerns with the above strategy:
- The common docs need to appeal to a wide audience. So beginner-friendly content might be annoying for advanced users, while any advanced material would be confusing and beyond the scope of beginners. I think we could address this concern with thoughtful page layout.
- Beginners might get lost in a web of docs (especially if there are lots of links to related material), and read a lot more than necessary for completing the exercises.
- The book would be less self-contained.
- This might not be the original intention of the book.
I don't think it's possible to balance the needs of advanced users who need reference-style docs with beginners who need tutorials in the same documentation resource, they really need to be kept separate. So I don't think a single common/primary source is possible unfortunately, at least not in the way you're thinking.
The earliest this is covered is in Ch10, but I think it would also be fitting to cover this in Ch6 too, since it will be helpful for some Ch7 exercises.