add compose's doc

[Jobhdez]

[stylewarning]

Don't reference parameter names in Coalton docs, because they won't show up on the html doc. Also the example should be in the docstring.

Is "don't reference param names" really that reasonable? Param names in practice carry useful information (e.g., "needle", "haystack"), and not everything can be buttoned up nicely in an abstract description. It sounds like a deficiency of our doc system, not of the doc comment.

[eliaslfox]

It sounds like a deficiency of our doc system

I guess so. Haddock doesn't show parameter names. Haskell docs just say "the first" and "the second". It's definitely changeable, but until we do, I'd rather keep parameter names out of new docstrings.

[stylewarning]

Isn't Haskell renowned for people getting confused which arguments do what?

[eliaslfox]

That hasn't been my experience

[stylewarning]

Anyway, I'm fine with (temporarily) preferring a style which excludes argument names, if and only if the doc string isn't less clear or doesn't result in discombobulation.

[gefjon]

Isn't Haskell renowned for people getting confused which arguments do what?

This has been my experience; for functions with more than two arguments, especially of the same type, I find it difficult to parse and understand Hackage documentation because I have to keep track of the arglist in my head, which pretty much always amounts to me trying to reconstruct meaningful names for the arguments and substituting them into the documentation.

Anyway, I'm fine with (temporarily) preferring a style which excludes argument names, if and only if the doc string isn't less clear or doesn't result in discombobulation.

I think my preferred stopgap here would be to include the arglist in the docstring, rather than not referring to the names at all. In this example, I think I'd want to write something like:

"(compose outer inner) constructs a function that, given an argument X, computes (outer (inner x))."

[stylewarning]

Maybe we can convince first-time contributor @Jobhdez to add the lambda list args to the doc generator to really wrap up this PR? 😁 I'm kidding.

I don't mind either which way, and I definitely won't petition to retroactively change all of the functions in the stdlib, but I think @gefjon's stopgap is fine. I'm also partial to the slight rewording

Given functions f and g, compute ...

But that's just me bikeshedding. @gefjon is certainly no less clear.