Improve documentation for Control.Monad.State

Offen
  • Stimmt etwas nicht?
#149 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Anfängerfreundlichkeit
52/100
Issue-Typ
Dokumentation
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Bereich
documentation

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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!

Vorherrschende Sprache
PureScript
Sterne
72
Forks
43
Ø Merge
2 T. 23 Std.
Gemergte PRs (30 T.)
1

Entwicklungsumgebung

  • Kein Dockerfile und keine Docker-Compose-Datei
  • Hat eine Pull-Request-Vorlage
  • Kein Beitragsleitfaden

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus purescript/purescript-transformers

Alle Issues in purescript/purescript-transformers

Ähnliche Issues

Weitere Issues zu Documentation

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.