Add scaladoc targeted at newcomers to type-derivation #436
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
As a fairly experienced programmer, but a newcomer to type-derivation and the terminology around Algebraic Data Types, I felt uncertain quite quickly when trying to use Magnolia, and would have found some Scaladoc helpful! I'm not assuming that a developer would have to access rendered HTML scaladoc to get value from this additional documentation - for instance, the way I normally consume scaladoc is clicking through to the original library source code in my IDE, and reading the scaladoc next to the code. In particular, I found these things puzzling as a newcomer, and have tried to provide explanation/context (which may be wrong!) on them: * What's the full list of methods needed to implement a derivation? * Why are they called join & split? * What would a typical way to implement them be - where are the examples of usage? Some of the descriptions in the Scaladoc may look a little obvious or unnecessary to experienced users of the library - the wording may appear almost equivalent to the type signature of the method, but I do think spelling these things verbally is helpful to new users!
|
Awesome additions- thank you! :) We are definitely missing docs in other places as well, so if you see somewhere lacking, please let us know |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As a fairly experienced programmer, but a newcomer to type-derivation and the terminology around Algebraic Data Types, I felt uncertain quite quickly when trying to use Magnolia, and would have found some Scaladoc helpful!
I'm not assuming that a developer would have to access rendered HTML scaladoc to get value from this additional documentation - for instance, the way I normally consume scaladoc is clicking through to the original library source code in my IDE, and reading the scaladoc next to the code.
In particular, I found these things puzzling as a newcomer, and have tried to provide explanation/context (which may be wrong!) on them:
Some of the descriptions in the Scaladoc may look a little obvious or unnecessary to experienced users of the library - the wording may appear almost equivalent to the type signature of the method, but I do think spelling these things verbally is helpful to new users!