STM foreach docs confusing

[drue]

This is a request to clarify the documentation around the foreach method of the various transactional data structures (TSet, TMap, TArray).

The docs say only that "foreach is used for performing side-effect for each element in [type]" This is the entirety of the documentation and is cut and pasted into all of the TStructures docs. This is very confusing because the STM introduction says "Only STM actions and pure computation may be performed inside a memory transaction. "

What makes this worse is every example is the same and showing foreach doing a println. Why would anyone using a functional effect library with built-in logging facilities want to do a println instead of ZIO.log?

I'm pretty sure anyone new to ZIO reading the docs wants to perform a ZIO effect for each element of the data structure. I don't think you can do this even though the Chat will tell you otherwise. It might tell you to wrap the effect in STM.succeed but of course that doesn't execute the effect. I went round and round with the chat and searched the internet and couldn't find anything beyond "here's how to do a println!"

I'm pretty sure it can't be done, you have to extract the data into a normal set/map/list/array and do the foreach outside the STM transaction even though the existence of and documentation for the foreach method suggest otherwise.

Please update the docs to show how to use foreach to perform a ZIO effect for each element of the TSet/TMap/TArray or explain what foreach is meant to be used for because right now it is very confusing.

[kyri-petrou]

Did you mean to open this issue in https://github.com/zio/zio instead?

[drue]

yes, just about to close and reopen thanks for quick response