The Arrow 2.0.0 API is awesome!! :arrow::rocket: ...

# arrow

[Iliyan Germanov]

The Arrow 2.0.0 API is awesome!! arrow🚀 I just tried on a personal Kotlin Compose Multi-platform (Android & Desktop) project and it's smooth! Still haven't explored much - will do in the following weeks but here's some feedback.

What I liked:
• Effects are no longer suspend - it was annoying to mark pure functions with "suspend" in the past versions
• The Raise<A> API is simple and when combined with context receivers makes the code easier to read by just glancing at the function types.
• Overall what I've seen is intuitive easy to use - haven't even read the docs on the new website
What can be improved:
• Couldn't figure out the best way to short-circuit catch({}){}. Are there docs on that? Code in the 🧵
• The KDoc is minimal and lacks examples. For example, on raise() we have just "Raise a logical failure of type Error". Btw GPT-4 generate killer docs if you give him some context and good prompts - ofc it needs human verification but it can greatly speed-up the docs process.
• Other than that - you've done an excellent job! I really enjoy to upgrade! 👏

[Iliyan Germanov]

Code example:
https://github.com/Ivy-Apps/ivy-wallet/blob/multiplatform/core/src/commonMain/kotl[…]/core/exchangerates/provider/FawazahmedExchangeRatesProvider.kt

[Iliyan Germanov]

Can this be done better? I don't want to throw IllegalStateException with error()

context(HttpClient)
    private suspend fun fetchRatesFrom(url: String): Either<String, FawazahmedResponse> = catch({
        withContext(<http://Dispatchers.IO|Dispatchers.IO>) {
            val response = get(url)
            if (!response.status.isSuccess()) {
                error("Unsuccessful response code - ${response.status.value}: ${response.body<String>()}")
            }
            Right(response.body())
        }
    }) { e: Exception ->
        Left(e.message ?: "Unknown error")
    }

[Iliyan Germanov]

Example of GPT-4 generated KDoc with zero human editting:
https://github.com/Ivy-Apps/ivy-wallet/blob/multiplatform/core/src/commonMain/kotlin/ivy/core/data/primitives/PositiveDouble.kt

[simon.vergauwen]

context(HttpClient)
    private suspend fun fetchRatesFrom(url: String): Either<String, FawazahmedResponse> = catch({
        withContext(<http://Dispatchers.IO|Dispatchers.IO>) {
            val response = get(url)
            if (!response.status.isSuccess()) {
                error("Unsuccessful response code - ${response.status.value}: ${response.body<String>()}")
            }
            Right(response.body())
        }
    }) { e: Exception ->
        Left(e.message ?: "Unknown error")
    }

You probably just want either with nested `catch`around get. If you don't mind get throwing unexpected failures, you can also omit the catch. Some more information: https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/#from-exceptions

context(HttpClient)
private suspend fun fetchRatesFrom(url: String): Either<String, FawazahmedResponse> =
  either {
        withContext(<http://Dispatchers.IO|Dispatchers.IO>) {
            val response = catch({ get(url) }) { e: Exception ->
              Left(e.message ?: "Unknown error")
            }
            ensure(response.status.isSuccess()) {
"Unsuccessful response code - ${response.status.value}: ${response.body<String>()}"
            }
            response.body()
    }

[simon.vergauwen]

About the docs.. we were still unsure on if we want to provide so much KDoc in the code.. everything is now on the website, but we can move some in both places as well.

I guess it's not lacking when reading KDoc inside IDEA only, instead of having both website and IDEA open.

[Iliyan Germanov]

TIL, I can nest either and catch - awesome. Thank you for the refactoring, I like it!

Regarding the docs, as a lazy dev who uses only one screen, I'd like to have everything I need in IDEA. I want to be able to press "CTRL + Q" and see short explanation + examples on every method, type everything. I know that this is overkill for you but hey we the community can help.

IMO, the benefit of doing this is that it'll help newcomers to FP and Arrow greatly. For example the thing you shown me above may deserve a place in the either or catch

[simon.vergauwen]

Right, super valid point. I am going to put some time on this after KotlinConf 👍
Contributions also welcome of course ☺️

https://github.com/arrow-kt/arrow/issues/3037

[Iliyan Germanov]

I'll try to help when I have some spare time 🙂
Raised this small PR adding KDoc around Raise.