I m looking at the source code of Arrow and I ve noted that

Question

I m looking at the source code of Arrow and I ve noted that there are interfaces like `Functor` which are very well documented but there are things like `Profunctor` which have literally no docs The functions are also a bit problematic because their kdocs are mostly hard to understand or non existent Do you plan on improving this It would be useful for contributors who didn t come from a Scala background

addamsson · Answer

For example I have no idea what `Applicative` can be used for and what `unit` means in it without looking at the code

addamsson · Answer

It would be tremendously useful to include not only docs but real life examples for the application of these things

simon.vergauwen · Answer

Yes we have this planned and we ve worked very hard on a solution to compile and test the snippets in the kdoc and host them our website as runnable snippets in the documentation

addamsson · Answer

I think I can help although I have no formal FP background

simon.vergauwen · Answer

Our focus currently lies with Kotlin MPP and stabilizing towards Arrow 1 0 We d love contributions to the documentation and we d love to help anyone who is interested in doing so

simon.vergauwen · Answer

That d be awesome

addamsson · Answer

I ve been using Arrow since its inception but I find some of its APIs unintuitive

addamsson · Answer

I understand that in most of the cases it is straightforward for someone who comes from a Scala background but for someone who worked with Java Clojure previously it is very unintuitive

simon.vergauwen · Answer

All feedback is welcome There is some low hanging fruit that we re aware off and stream lining the apis is on the roadmap

simon.vergauwen · Answer

Any concrete examples

addamsson · Answer

For example there is `Eq`

addamsson · Answer

It causes a mental pagefault to interpret it

addamsson · Answer

If I read the kdocs I can see that it is there to check equality

addamsson · Answer

good

addamsson · Answer

but now I see `eqv` and `neqv` which is also not too hard to interpret

addamsson · Answer

but this mental overhead adds up and I end up spending a lot of time interpreting code instead of reading it

addamsson · Answer

I think using plain English would be better

addamsson · Answer

something like

addamsson · Answer

`foo isEquivalentTo bar `

addamsson · Answer

I also don t see the point of not using ` equals other Any Boolean`

addamsson · Answer

that would give operator overloading for `==` and ` =`

addamsson · Answer

I think that these things are no brainers for those who have the context the contributors of the project

addamsson · Answer

but the users of arrow are hindered by it

addamsson · Answer

I think that by providing readable APIs would make Arrow s adoptation skyrocket

addamsson · Answer

complete with real life examples for things like `Applicative`

addamsson · Answer

I read 3 different definitions for what an `Applicative` is and I didn t understand why it was useful until I saw the `Validation` class in VAVR

simon.vergauwen · Answer

The point of `Eq` is that you can compose it in nested shapes and it type checks

simon.vergauwen · Answer

Understanding why defining logic by behavior instead of type makes more sense if you approach it the other way around imo

simon.vergauwen · Answer

Starting from the more powerful use cases like writing abstract validation logic and running it accumulating `Validated` vs short circuit `Either`

simon.vergauwen · Answer

Or writing abstract concurrenct code and running it with RxJava Reactor and Flow

simon.vergauwen · Answer

But I m having a hard time writing this down in an easy to understand way sweat smile like a lot in the FP world I think

addamsson · Answer

I get the behavior vs type argument

addamsson · Answer

and I agree with that

addamsson · Answer

my point was that I think it can be made more approachable

simon.vergauwen · Answer

The difference between `equals` and `Eq` is essentially inheritance vs composition So if you ask why not `equals` vs `Eq` you could also ask inheritance vs composition

addamsson · Answer

with names which don t require much interpretation

simon.vergauwen · Answer

There is definitely room for improvement

simon.vergauwen · Answer

I m too used to this naming I don t see it anymore

addamsson · Answer

I see

addamsson · Answer

that s why I m trying to be the fresh set of eyes with no domain knowledge whatsoever smile

simon.vergauwen · Answer

Yes It would be great if you could keep track of this in a ticket

addamsson · Answer

hmm

addamsson · Answer

good idea

addamsson · Answer

this is not about `Eq` but the whole API

simon.vergauwen · Answer

Yep all feedback is great Especially if we can improve more before 1 0

addamsson · Answer

Do you agree with the overall sentiment that Arrow is a bit of an oddball for those who are used to how the Kotlin stdlib works and the readability of the API can be improved

simon.vergauwen · Answer

Well I think the Kotlin std is the oddball I don t expect `setOf 1 2 3 map` to return List

simon.vergauwen · Answer

I m not on my computer atm but there are cases like that

simon.vergauwen · Answer

We re trying to improve the API without changing the signatures if that makes sense

simon.vergauwen · Answer

I ve done some investigating on Optics and stuff like named lambda params can also drastically improve the API imo In addition with good kdocs I think we d improve things a lot

simon.vergauwen · Answer

Also simpler apis with the result of keep 87 will drastically improve things removing the need of enabling syntax with `run`

addamsson · Answer

you have a point

addamsson · Answer

what I meant is that the names could be improved

addamsson · Answer

to be intuitive for those who are not yet familiar with FP

addamsson · Answer

i m just trying to get on the same page as you

simon.vergauwen · Answer

Yes we re on the same page I just wanted to clarify to avoid confusion

addamsson · Answer

got it

addamsson · Answer

you mean that the stdlib is oddball from a correctness perspective it is weird that `List`s are returned for example

simon.vergauwen · Answer

Exactly but besides that we do have the freedom to change things around to make them more user friendly

addamsson · Answer

my argument is that Arrow is an oddball from a readability pragmatic programmer standpoint I don t really care in most of the cases that a `List` is returned but I want my code to be readable so when the next guy comes around to maintain my code and they don t know Arrow they at least have a chance to understand what i ve written by just looking at it

simon.vergauwen · Answer

Yes absolutely Do you feel like this is the case with Vavr From my Java work experience of the passed 4 years I ve experienced a lot of pushback for things like Vavr in Java but that might ve been region specific

simon.vergauwen · Answer

And if so do you feel this is because of the laxer APIs Or is that irrelevant

addamsson · Answer

I haven t used it for a long enough time to be able to tell

addamsson · Answer

but I ve had this experience with Arrow

addamsson · Answer

If you check the Issues and even the issue about keep 87 you can see that people are asking for things like using `Composable` instead of `Monoid`

addamsson · Answer

I dont agree with them because you can look up what a `Monoid` is and is is unambiguous

addamsson · Answer

but the names of functions are kinda arbitrary

addamsson · Answer

for example to construct a `Functor` I ve seen things like `pure` `of` `just`

addamsson · Answer

if would be nice to have something readable which is familiar for Java devs as well

addamsson · Answer

I like `of` because it is part of Effective Java and most folks understand it by looking at it

simon.vergauwen · Answer

Yes we had `pure` because originally we thought that since Arrow is build for FPers it should be immediately clear to anyone with FP experience

simon.vergauwen · Answer

We ve moved away from that train of thought In this case we choose for `just` because it s well know from RxJava and Reactor

simon.vergauwen · Answer

Having a lot of aliases is something we wanted to avoid since having multiple ways of doing is probably a bigger drawback

simon.vergauwen · Answer

I find naming extremely difficult and especially in Arrow because we d like to take in account multiple audiences

addamsson · Answer

I see

addamsson · Answer

I agree with the alias problem

addamsson · Answer

There is one important question though

addamsson · Answer

what is the purpose of Arrow itself

addamsson · Answer

are you writing it for Scala Haskell expats

addamsson · Answer

are are you writing it for the general populace

addamsson · Answer

for the pragmatic everyday programmer

simon.vergauwen · Answer

The purpose of Arrow is for everyone to be able to do pure FP in Kotlin The important part here is that we want to stay pure in all APIs because that s what we feel brings the most benefit and thus makes the most sense

simon.vergauwen · Answer

We re not writing it for the occasional Scala Haskell guy We expect most developers already heavily invested in FP in those languages will probably not switch

simon.vergauwen · Answer

Ideally it should be able to suit everyone s needs depending on your needs you d import more or less modules

addamsson · Answer

This is great

addamsson · Answer

but in this case there has to be some reconciliation

addamsson · Answer

to make Arrow approachable for PEP s Pragmatic Everyday Programmer

addamsson · Answer

For example right now if I want a `ListK` which I figured out I ll need if I want to tamper with the list with some elements the familiar syntax from the stdlib would be `listKOf 1 2 3 `

addamsson · Answer

but instead I need to do this `listOf 1 2 3 k `

addamsson · Answer

and if I look at the code I see this

addamsson · Answer

``` fun lt A gt List lt A gt k ListK lt A gt = ListK this ```

addamsson · Answer

I can see that this creates a `ListK` but I have no idea what the `k` means

addamsson · Answer

looking at the code of `ListK` it says it is a wrapper but I see no explanation of the `K` Is it because it is a kind It has a ` higherkind` annotation But then why the docs says it is just a wrapper Why not `ListW` then or `ListWrapper` And I still can t remove an element form `ListK` because there is no such operation

addamsson · Answer

With VAVR for example it is just `List of 1 2 3 remove 1 ` and I get all the operations I need It is approachable and intuitive

addamsson · Answer

So if we want to add persistent data structures to Arrow there has to be a `remove` operation and a `persistentListOf 1 2 3 ` function

addamsson · Answer

otherwise users will just stare at the code complition and wonder how it works

simon.vergauwen · Answer

Good point about `listKOf` vs `listOf k `

simon.vergauwen · Answer

We already have a working compiler plugin that adds HKTs

addamsson · Answer

I give you a counter example

addamsson · Answer

``` Try invoke require 1 == 2 map println Sorry I won t be printed ```

addamsson · Answer

this is pretty intuitive

addamsson · Answer

i ve never used Arrrow s `Try`

addamsson · Answer

but just using code completion i was able to do this in 5 seconds