Improve documentation for Control.Monad.State

オープン
  • 何か問題がありますか？
#149 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
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時間
マージ済み PR（30日）
1

環境構築

  • Dockerfile・Docker Compose ファイルなし
  • プルリクエストのテンプレートあり
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

purescript/purescript-transformers のほかの issue

purescript/purescript-transformers の issue をすべて見る

似ている issue

Documentation の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。