Add Nomenclature / Cheatsheet page #2558
Conversation
Codecov Report
@@ Coverage Diff @@
## master #2558 +/- ##
=======================================
Coverage 95.14% 95.14%
=======================================
Files 361 361
Lines 6630 6630
Branches 289 283 -6
=======================================
Hits 6308 6308
Misses 322 322Continue to review full report at Codecov.
|
|
This is great! Perhaps "Nomenclature" isn't the right term, it's more of an overview, or cheatsheet, or index of the major functions? (disclaimer: I made something similar, as a PDF, at https://arosien.github.io/cats-cheatsheets/typeclasses.pdf) |
|
@arosien Well, I am really sorry to say, I did not know of your cheatsheet. Otherwise, I would have saved me some time by |
This commit introduces a new page to the documentation, showing the name and simplified type signatures of the methods in the type classes and data types of the cats library. Whereas other pages of the documentation try to explain one type-class at a time in a manner that is amenable to beginners; whereas the Scaladocs are good only for those who remember the name of the type-class and want to recall what they do. ScalaDocs, in particular, suffer from a limitation: they are structured following the classes-packages-objects structure of the Scala codeHowever, practitioners using a type-class or a data type may be interested on browsing easyily through different methods that may be defined in separate "modules".
|
I am putting this to submission, and removing the WIP label. While this page may be further refined, the current version is wide enough for a first version. |
docs/src/main/tut/nomenclature.md
Outdated
| - Type signatures are currified, parameters are taken one at a time, and they are separated with the arrow `=>` operation. This simplifies Scala's use of several lists of parameters. | ||
| - We ignore from the type signatures any implicit parameters, and instead add them as constraints at the side. | ||
| - We ignore the distinction between by-name and by-value input parameers, so we just use the type for both. Instead, we use the notation `=> A`, without any parameters, to indicate constant functions. | ||
| - We ignore the distinction between the Scala traits of `Function` and `PartialFunction[A, B]`. Thus, we use in both cases the symbol `A => B` to indicate both a `Function[A,B]`, and a `PartialFunction[A,B]`; and for partial functions we add a note besides it. |
There was a problem hiding this comment.
and for partial functions we add a note besides it
hmm.. I didn't see the note besides partial functions (at least not in ApplicativeError). I don't mind if we add them in a separate PR though, but we probably want to remove this sentence before merge.
|
Thanks so much @diesalbla! This is amazing. I left a minor comment. |
docs/src/main/tut/nomenclature.md
Outdated
|
|
||
| Because `cats` is a library for Scala, and because Scala has many more knobs and switches, the actual definitions and implementations of some functions in the library can seem a bit too obfuscated at first sight. To alleviate this, in this glossary we focus on the plain type signatures of the method, and ignore many of the details from Scala. In particular, in our type signatures: | ||
|
|
||
| - We use `A,B,C` for type variables of kind `*`, and `F, G, H` for type variables of a higuer kind. |
- Attend code review comments, and mention PartialFunction. - Add section on the Kleisli data structure.
Adds a page with the types and names of the many functions and methods of
cats.The types are written in a Haskell-lke form, as separate currified type signatures, without the names of the parameters.