[axman6]

I’m sorry, but this is an astoundingly ridiculous point of view. Those type variables CAN’T be named anything better because they could be absolutely anything at all, that’s the point of generic types.

You are complaining that a single function within a library doesn’t describe the whole abstraction the library is built on? Should every single function, operator and type include the whole fucking lens tutorial so you don’t have to go and find it?

I suppose every web library should include an explanation of IP, TCP, UDP, HTTPS, url encoding, compression and anything else that is needed, on every single function too? Christ, I cannot believe how incredibly dumb your take here is. Libraries in every single language provide some kind of preamble in their documentation which covers what abstraction that library provides, and Haskell is no different; the particular library you have chosen to misunderstand is INCREDIBLY general, the documentation is actually amazingly precise, if you have taken the time to learn what an optic is.

I genuinely think you should be ashamed of this opinion, because it shows that you’re both willingly ignorant, and proud to state that fact publicly.

[tome]

There are ways of making your point that wouldn't descend into personal attacks. Please don't give Haskellers a bad reputation!

[spion]

Don't worry, I really enjoy being called dumb and ignorant. Its truly the best way to make me stop and listen to the other side so I can find out what my mistake was.

[spion]

Why should I be ashamed by pointing out poor library documentation practices?

> Those type variables CAN’T be named anything better because they could be absolutely anything at all, that’s the point of generic types.

I was talking about the word "rule" and the verb "rewrite", and was explaining how the Rust documentation is explicit what is what (The type variable 'a refers to <X>). Similarly, the docs here can be explicit about which part is the rule and which part is the thing being rewritten.

I don't like guessing, but I will try and guess which thing refers to which and try to rewrite the doc myself

> ASetter a b a b -> (b -> Maybe a) -> a -> bSource

> Rewrite (ASetter a b a b) by applying the rule (b -> Maybe a) everywhere it can be i.e. everywhere the function returns `Just a`.

Now, for this part

> Ensures that the rule cannot be applied anywhere in the result:

> propRewriteOf l r x = all (isNothing . r) (universeOf l (rewriteOf l r x))

I would hazard a guess to try and translate that to

Ensures that the rule cannot be applied anywhere where the rule function returns `Nothing`

Did I get these right? Hell if I know. Maybe the Setter is the rule. Maybe that `universe` crap means something else, because sure, the best way to document a function is to describe it with code using yet another poorly documented function (not).

Why are you so defensive? Are haskellers incapable of learning from any negative feedback?

Am I willfully ignorant by pointing out how the documentation can be improved, and by giving examples how other languages take the approach I'm describing? Well written library documentation describes all input and output types explicitly. That's it, thats my claim. Do you contest that claim? Is it impossible to specify which part of that type is a rule and which part is the thing being rewritten, in the docs? Why? Do you think that's good documentation practice?

To answer your questions explicitly

> You are complaining that a single function within a library doesn’t describe the whole abstraction the library is built on?

No, I ask that the documentation describe which nouns refer to which parts of the type

> Should every single function, operator and type include the whole fucking lens tutorial so you don’t have to go and find it?

No, they should include enough description to know what every part of the type refers to in the documentation text.

> I suppose every web library should include an explanation of IP, TCP, UDP, HTTPS, url encoding, compression and anything else that is needed, on every single function too?

No, but it should explicitly state which part of its arguments refers to which concept (IP address, URL, etc), except perhaps when the argument name contains a reference to that concept and the name is clearly visible in the documentation

> Christ, I cannot believe how incredibly dumb your take here is.

Did you actually read my take, or did you knee-jerk into the typical "OMG YOU CAN'T DESCRIBE TYPE ARGUMENTS THEY'RE ABSTRACT" reaction? Yes, I know those types don't have meaning outside of a context. No, that is not what I was asking. (Although, poorly named positional type arguments are pretty dumb, but thats a story for a different day)

> Libraries in every single language provide some kind of preamble in their documentation which covers what abstraction that library provides, and Haskell is no different

They also make the connection between the argument types and the nouns used in the documentation. Something that is made more difficult in Haskell because the argument names are omitted from the generated documentation and often poorly written.

> the particular library you have chosen to misunderstand is INCREDIBLY general, the documentation is actually amazingly precise, if you have taken the time to learn what an optic is

I've spent anywhere between 6-12 hours on lens tutorial and optics, 4 of which on the SPJ videos. Doesn't make this documentation more clear, however. Please, do tell me how dumb I am. I'm totally listening, because thats how you are supposed to react when someone provides feedback.

> I genuinely think you should be ashamed of this opinion, because it shows that you’re both willingly ignorant, and proud to state that fact publicly.

Please take a step back, and read again what I propose with an open mind. Don't take the criticism as a personal attack.

I honestly did my best to describe what I believe is wrong with the whole Haskell documentation culture, because someone asked. I haven't seen anything here to change my mind.