Improve documentation for Control.Monad.State

未關閉
  • 哪裡不對？
#149 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

評估

難度
2/5
預估耗時
1-3 小時
新手友好度
52/100
Issue 類型
文件
描述清晰度
基本清楚
活躍度
停滯
領域
documentation

研究方向

Find the documentation for State in Control.Monad.State and compare it with the MonadState documentation in Control.Monad.State.Class. Add an explanation of what State means beyond its type alias, including its relationship to MonadState. Done when readers can understand that relationship from the State documentation; the issue names no specific files or tests.

由索引模型根據 Issue 內容生成。

描述

The documentation for State in Control.Monad.State gives State's type definition as as type StateT s Identity, and says that "The State monad is a synonym for the StateT monad transformer, applied to the Identity monad."

That documentation simply repeats whats' in the type signature, but I have to assume that I'm not alone in finding the type signature opaque. Understanding it requires studying StateT and Identity, and then figuring out what the implications of their combination are.

There's information that seems relevant in the documentation for MonadState in Control.Monad.State.Class, but it's not easy to figure out what the relationship is between MonadState and StateT s Identity. It doesn't seem as if one is normally supposed to use MonadState directly, in any event.

Purescript by Example has some discussion of the State monad. It's helpful, but it's fairly superficial and didn't answer my questions. I didn't find anything helpful for my needs in Jordan's Reference, though it's possible that I haven't looked in the right place. Instead I've been studying Haskell resources to learn about Haskell's Control.Monad.State, which is obviously the model for Purescript's State. However, then one has to worry about possible differences in corner cases or even more substantial semantical features. This becomes a real issue when I translate Haskell code into Purescript and get an error that isn't due to obvious differences between the languages. (e.g. it's obvioius using (x, y) instead of Tuple x y is a mistake). Then it's not clear whether I made a mistake, or whether there's difference in the semantics of the two State monads. Since it's hard to understand the documentation for Purescript's State, figuring out whether there's a difference isn't easy. (The documentation for Haskell's State is confusing, too, but the docs are more detailed, and there are lots of other things one can read about Haskell's State.)

Normally, I'd expect that more explanation of something like the State monad might be found in the package documentation. However, since the Control.Monad.* modules are part of the transformers package, and there are lots of other modules in that package, I can understand why the package documentation doesn't say anything about particular modules or groups of modules.

However, I think there needs to be documentation of State that goes beyond it's type alias definition. One small thing that might help would be a brief explanation within the documentation for State of its relationship to MonadState.

Thanks!

主要語言
PureScript
星號
72
分支
43
平均合併
2 天 23 小時
30 天內合併 PR
1

環境準備

  • 沒有 Dockerfile 或 Docker Compose 檔案
  • 有 Pull Request 範本
  • 沒有貢獻指南

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

purescript/purescript-transformers 的其他 Issue

查看 purescript/purescript-transformers 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。