search

arrow-kt / arrow-fx

Λrrow Fx is part of Λrrow, a functional companion to Kotlin's Standard Library
http://arrow-kt.io
Other
64 stars 15 forks source link

Add a lot more documentation to STM and structure it better #302

Closed 1Jajen1 closed 3 years ago

1Jajen1 commented 3 years ago

So after seeing the rendered api docs for STM I wasn't quite satisfied. It was really hard to see which methods worked on which datatype and what the datatypes actually did.

This hopefully addresses that issue by documenting the datatypes with the methods used to operate on them. It also adds a ton of simple examples and changes/adds a few operator overload methods to be more like the stdlib collections.

Edit: This is 95-99% documentation btw^^ So don't be scared by +2000 here :see_no_evil:

1Jajen1 commented 3 years ago

Oh and also: Is there a place in the arrow-fx docs sidebar that we can feature STM in? Apidocs is ok-ish but adding it to like datatypes as well would be a bit better imo. Just not sure it fits there.

nomisRev commented 3 years ago

@1Jajen1 need to make some time to go through this, but feel free to restructure the Arrow Fx website a bit to make room for STM in the sidebar. Perhaps we need to relocate data types under an Arrow Fx Coroutines specific section? We might also want to make room for more modules later on in a similar style.

https://github.com/arrow-kt/arrow-site/blob/master/docs/_data/sidebar-fx.yml

1Jajen1 commented 3 years ago

We might also want to make room for more modules later on in a similar style.

Likely as this will apply to Stream as well.

I'll try to think of something, but as of now I don't have a good idea what the category for STM (or Stream) should be...

nomisRev commented 3 years ago

We could change the Data types section to Arrow Fx Coroutines, and we can add a section for STM and Stream? I am working on the split of Streams atm ;)

nomisRev commented 3 years ago

A second review is needed @arrow-kt/maintainers

1Jajen1 commented 3 years ago

I requested some changes regarding type names and operator names to make it closer to our efforts to be inline with the std lib semantics and make some types like TSem more exploit if possible.

Yes please, now is the perfect time to align the api, I took the names from the haskell libs and related so any change is fine by me. I'll do it in this pr if that is fine with you.

PhBastiani commented 3 years ago

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM 👏

A README explaining the main functionalities would be useful to introduce the purpose of the module.

1Jajen1 commented 3 years ago

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM

A README explaining the main functionalities would be useful to introduce the purpose of the module.

Thanks for reading it :pray:

The README: Regarding the implementation or the api function? I suppose a readme describing how the implementation works ala fx-coroutines makes most sense as the rest should be in the docs^^

1Jajen1 commented 3 years ago

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM A README explaining the main functionalities would be useful to introduce the purpose of the module.

Thanks for reading it pray

The README: Regarding the implementation or the api function? I suppose a readme describing how the implementation works ala fx-coroutines makes most sense as the rest should be in the docs^^

Either way I think its best left for another pr as this one is quite close to completion. For a general introduction to what STM can do the api docs for the STM interface and the documentation for atomically are the best start.

PhBastiani commented 3 years ago

Either way I think its best left for another pr as this one is quite close to completion. For a general introduction to what STM can do the api docs for the STM interface and the documentation for atomically are the best start.

We don't need a long README: a short introduction would be sufficient, as long as the reader is encouraged to read the STM class doc (I mean it is important to mark the main entry point of the API).

1Jajen1 commented 3 years ago

We don't need a long README: a short introduction would be sufficient, as long as the reader is encouraged to read the STM class doc (I mean it is important to mark the main entry point of the API).

Ah ok, I was confused by what exactly you were referring to. I'll add that in this pr, thanks for the suggestion! At some point I'll add a section to it which explains the internals as a sort of contribution guide like arrow-fx-coroutines does atm, but thats a later pr.

nomisRev commented 3 years ago

At some point I'll add a section to it which explains the internals as a sort of contribution guide like arrow-fx-coroutines does atm, but thats a later pr. ❤️

1Jajen1 commented 3 years ago

Added a readme which contains a link to the STM interface api docs. We still need a section in the sidebar, but until I have a decent idea where, that can wait.

If there is nothing else I'll merge this pr later today :tada: