Improve documentation for Control.Monad.State

Aberta
  • Algo errado?
#149 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
52/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Domínio
documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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!

Linguagem predominante
PureScript
Estrelas
72
Forks
43
Merge médio
2d 23h
PRs com merge (30d)
1

Preparar o ambiente

  • Sem Dockerfile nem arquivo Docker Compose
  • Tem um modelo de pull request
  • Sem guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de purescript/purescript-transformers

Todas as issues de purescript/purescript-transformers

Issues semelhantes

Mais issues de Documentation

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.