4 ms·

> Hoogling show this is an alias of https://hackage.haskell.org/package/lens-5.1.1/docs/Control- https://hackage.haskell.org/package/lens-5.1.1/docs/Control-...

by spion 4y ago

> Hoogling show this is an alias of https://hackage.haskell.org/package/lens-5.1.1/docs/Control- https://hackage.haskell.org/package/lens-5.1.1/docs/Control-... That explains nothing? What does it do? How does it do it? What do the type variables `a b a b` mean? Why are there 4 of them? What is ASetter?

spion 4y ago
Oh the documentation of Setter is fun: https://hackage.haskell.org/package/lens-5.1.1/docs/Control-Lens-Combinators.html#t:Setter https://hackage.haskell.org/package/lens-5.1.1/docs/Control-... Absolutely nothing explained whatsoever. Yup, sounds like like the typical, familiar Haskell experience of zero useful docs where you need them.
- axman6 4y ago
  This argument is literally “the documentation for this domain I don’t understand is bad because I refuse to learn the domain”. I use the lens library all the time and those docs make perfect sense, particularly if you apply just the teensiest bit of logic and thing “Could a setter, perhaps, set something?”. It’s a DSL, and you don’t understand the domain - I’m sure you’d have a great time explaining this function from LLVM without referring to any other part of the documentation to give it context https://llvm.org/doxygen/group__LLVMCCoreValueInstructionGetElementPointer.html#ga1e623a49010f40ef27a4a7a955648898 https://llvm.org/doxygen/group__LLVMCCoreValueInstructionGet.... What’s a GEP? Under the rules you’re applying to the lens documentation, I’m not allowed to look that up, because it should be immediately obvious.
  - spion 4y ago
    Yes they actually document which bit is what > Get the source element type of the given GEP operator Notice the relentness repetition that provides precision and clarity? I now know the argument GEP is a GEP operator. Might seem redundant, but it allows a new reader to start from any point and find their way to the relevant terms / nouns and their types.
rowanG077 4y ago
The documentation of lenses is geared towards people know what lenses are. Of course this single fragment of documentation doesn't make sense if you don't know what lenses are. If you want to understand what lenses are the package links to a helpful wiki and tutorial: https://github.com/ekmett/lens/wiki/Overview https://github.com/ekmett/lens/wiki/Overview All within reach within seconds of discovering the function. To understand any tool you must understand the libraries and tools it to some degree. Your questions here are not Haskell specific, and the answers to the question you asked are easy to find. I'm not familiar with the Dhall code base and was able to answer you within minutes.
- spion 4y ago
  Documentation for people that already know what the thing is is called "useless documentation". Its not within any reach whatsoever. The overview isn't linked anywhere in Setter. Rule of writing documentation: if you're not going to write anything useful in the docs from a user perspective, don't pretend to write any docs at all. Oh, and also, that link you posted still doesn't answer what does `rewriteOf` actually do. Going back to the original docs of rewriteOf (https://hackage.haskell.org/package/lens-5.1.1/docs/Control-Lens-Combinators.html#v:rewriteOf https://hackage.haskell.org/package/lens-5.1.1/docs/Control-...) > Rewrite by applying a rule everywhere you can Rewrite what? In what? By applying what rule? Which type is the type being rewritten here? Which type is the rule? Completely unclear. This is not how you write library documentation, at all. Tutorials and overviews won't cut it - you need clear API docs, which are written by providing unabiguous explanation of the function inputs, function outputs and how they relate to each other. (Yes, this is tedious and yes it often involves repetition, but it means a ton for actual library usability) If there was one recommendation I could give to all Haskell library authors, it would be to explicitly assign an unabiguious descriptive alias noun to every argument within the text that describes their function. In the `rewriteOf` case, that would look something like this: > Rewrite the type (insert type found in the argument list here) by applying the rule (insert type of the rule in the argument list) everywhere you can.
  - spion 4y ago
    Oh the overview page is even worse for readability _1 :: Lens' (a,b) a is used immediately after set :: Lens' a b -> b -> a -> a which completely messes with anyone who's mind works in a way that makes it extremely difficult when symbols are immediately reused with completely different meanings. To summarize, Haskell documentation communication is biased against linguistically clear explanations and towards mathematically precise, symbolic "explanation", and those who are used to unnecessarily struggling with the latter style due to their math background are more likely to "make it".

by spion 4y ago

spion 4y ago

Oh the documentation of Setter is fun: https://hackage.haskell.org/package/lens-5.1.1/docs/Control-Lens-Combinators.html#t:Setter https://hackage.haskell.org/package/lens-5.1.1/docs/Control-... Absolutely nothing explained whatsoever. Yup, sounds like like the typical, familiar Haskell experience of zero useful docs where you need them.

axman6 4y ago
This argument is literally “the documentation for this domain I don’t understand is bad because I refuse to learn the domain”. I use the lens library all the time and those docs make perfect sense, particularly if you apply just the teensiest bit of logic and thing “Could a setter, perhaps, set something?”. It’s a DSL, and you don’t understand the domain - I’m sure you’d have a great time explaining this function from LLVM without referring to any other part of the documentation to give it context https://llvm.org/doxygen/group__LLVMCCoreValueInstructionGetElementPointer.html#ga1e623a49010f40ef27a4a7a955648898 https://llvm.org/doxygen/group__LLVMCCoreValueInstructionGet.... What’s a GEP? Under the rules you’re applying to the lens documentation, I’m not allowed to look that up, because it should be immediately obvious.
- spion 4y ago
  Yes they actually document which bit is what > Get the source element type of the given GEP operator Notice the relentness repetition that provides precision and clarity? I now know the argument GEP is a GEP operator. Might seem redundant, but it allows a new reader to start from any point and find their way to the relevant terms / nouns and their types.

rowanG077 4y ago

The documentation of lenses is geared towards people know what lenses are. Of course this single fragment of documentation doesn't make sense if you don't know what lenses are. If you want to understand what lenses are the package links to a helpful wiki and tutorial: https://github.com/ekmett/lens/wiki/Overview https://github.com/ekmett/lens/wiki/Overview All within reach within seconds of discovering the function. To understand any tool you must understand the libraries and tools it to some degree. Your questions here are not Haskell specific, and the answers to the question you asked are easy to find. I'm not familiar with the Dhall code base and was able to answer you within minutes.

spion 4y ago
Documentation for people that already know what the thing is is called "useless documentation". Its not within any reach whatsoever. The overview isn't linked anywhere in Setter. Rule of writing documentation: if you're not going to write anything useful in the docs from a user perspective, don't pretend to write any docs at all. Oh, and also, that link you posted still doesn't answer what does `rewriteOf` actually do. Going back to the original docs of rewriteOf (https://hackage.haskell.org/package/lens-5.1.1/docs/Control-Lens-Combinators.html#v:rewriteOf https://hackage.haskell.org/package/lens-5.1.1/docs/Control-...) > Rewrite by applying a rule everywhere you can Rewrite what? In what? By applying what rule? Which type is the type being rewritten here? Which type is the rule? Completely unclear. This is not how you write library documentation, at all. Tutorials and overviews won't cut it - you need clear API docs, which are written by providing unabiguous explanation of the function inputs, function outputs and how they relate to each other. (Yes, this is tedious and yes it often involves repetition, but it means a ton for actual library usability) If there was one recommendation I could give to all Haskell library authors, it would be to explicitly assign an unabiguious descriptive alias noun to every argument within the text that describes their function. In the `rewriteOf` case, that would look something like this: > Rewrite the type (insert type found in the argument list here) by applying the rule (insert type of the rule in the argument list) everywhere you can.
- spion 4y ago
  Oh the overview page is even worse for readability _1 :: Lens' (a,b) a is used immediately after set :: Lens' a b -> b -> a -> a which completely messes with anyone who's mind works in a way that makes it extremely difficult when symbols are immediately reused with completely different meanings. To summarize, Haskell documentation communication is biased against linguistically clear explanations and towards mathematically precise, symbolic "explanation", and those who are used to unnecessarily struggling with the latter style due to their math background are more likely to "make it".