3 ms·

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

by 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".
- Karrot_Kream 4y ago
  The Lens library sucks even if you're fluent in advanced math and Haskell. In practice when I have to use Lens (usually with JSON), I just code golf it until it works because it's so damn impenetrable.
  - axman6 4y ago
    I couldn’t agree with this opinion less - lens is incredibly elegant, and very consistent. It is a DSL, and you need to spend some time learning the domain, but once you do you’ll find it hard to live without it. If that’s the way you use the library then you haven’t spent any time to learn how to use it.
- solomonb 4y ago
  If you apply `_1` to `set` then it specializes to `set _1 :: a -> (a, b) -> (a, b)`. Yes its confusing. It sometimes helps to give longer variables: _1 :: Lens' (fst, snd) fst set :: Lens' structure focus -> focus -> structure -> structure set _1 :: fst -> (fst, snd) -> (fst, snd) You are bumping up against the severe amount of polymorphism at play in the lens library. This makes it hard to build a mental model but is a tremendous source of expressiveness and utility.
rowanG077 4y ago
> Documentation for people that already know what the thing is is called "useless documentation". Right... Like the doc of the regex match function in Rust is useless because it doesn't explain regexes. https://docs.rs/regex/latest/regex/struct.Match.html https://docs.rs/regex/latest/regex/struct.Match.html Or the C# beginSocketfunction because it doesn't explain what TCP is. https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginconnect?view=net-6.0 https://docs.microsoft.com/en-us/dotnet/api/system.net.socke... Or the go Exec function in the sql package not explaining with SQL or databases are. https://pkg.go.dev/database/sql#DB.Exec https://pkg.go.dev/database/sql#DB.Exec Any function level documentation expects you to know the basics and the contexts of a library. Documentation on that level is most certainly not useless. It's the standard in every language, for every library. I don't feel like you are approaching this from a fair point of view so I will stop replying. Can't convince people who don't want to be convinced.
- spion 4y ago
  > I don't feel like you are approaching this from a fair point of view so I will stop replying. Can't convince people who don't want to be convinced. You asked what's wrong, I assumed you'd like to know what I think. To me it now looks like you wanted to prove me wrong instead. I summarized plenty of problems, with the biggest one being bad API docs due to lack of detailed arguments and return types description and labeling and bad naming practices in general. FWIW, I've watched 4 hours worth of video on Haskell lens by SPJ and I still don't find the documentation clear. It could simply be that I'm not clever enough. Well written API docs would definitely help with that too though.
  - jose_zap 4y ago
    You may use the optics package instead. It is a replacement for the lens octaves with a focus on good docs and better error messages: https://hackage.haskell.org/package/optics-0.1/docs/Optics.html https://hackage.haskell.org/package/optics-0.1/docs/Optics.h...
- spion 4y ago
  > Right... Like the doc of the regex match function in Rust is useless because it doesn't explain regexes. https://docs.rs/regex/latest/regex/struct.Match.html https://docs.rs/regex/latest/regex/struct.Match.html At least they name their type variables: > The lifetime parameter 't refers to the lifetime of the matched text C# do too: https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginconnect?view=net-6.0#system-net-sockets-socket-beginconnect(system-net-endpoint-system-asynccallback-system-object) https://docs.microsoft.com/en-us/dotnet/api/system.net.socke... - every function argument is named, labelled and described separately.

by spion 4y ago

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".

Karrot_Kream 4y ago
The Lens library sucks even if you're fluent in advanced math and Haskell. In practice when I have to use Lens (usually with JSON), I just code golf it until it works because it's so damn impenetrable.
- axman6 4y ago
  I couldn’t agree with this opinion less - lens is incredibly elegant, and very consistent. It is a DSL, and you need to spend some time learning the domain, but once you do you’ll find it hard to live without it. If that’s the way you use the library then you haven’t spent any time to learn how to use it.
solomonb 4y ago
If you apply `_1` to `set` then it specializes to `set _1 :: a -> (a, b) -> (a, b)`. Yes its confusing. It sometimes helps to give longer variables: _1 :: Lens' (fst, snd) fst set :: Lens' structure focus -> focus -> structure -> structure set _1 :: fst -> (fst, snd) -> (fst, snd) You are bumping up against the severe amount of polymorphism at play in the lens library. This makes it hard to build a mental model but is a tremendous source of expressiveness and utility.

rowanG077 4y ago

> Documentation for people that already know what the thing is is called "useless documentation". Right... Like the doc of the regex match function in Rust is useless because it doesn't explain regexes. https://docs.rs/regex/latest/regex/struct.Match.html https://docs.rs/regex/latest/regex/struct.Match.html Or the C# beginSocketfunction because it doesn't explain what TCP is. https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginconnect?view=net-6.0 https://docs.microsoft.com/en-us/dotnet/api/system.net.socke... Or the go Exec function in the sql package not explaining with SQL or databases are. https://pkg.go.dev/database/sql#DB.Exec https://pkg.go.dev/database/sql#DB.Exec Any function level documentation expects you to know the basics and the contexts of a library. Documentation on that level is most certainly not useless. It's the standard in every language, for every library. I don't feel like you are approaching this from a fair point of view so I will stop replying. Can't convince people who don't want to be convinced.

spion 4y ago
> I don't feel like you are approaching this from a fair point of view so I will stop replying. Can't convince people who don't want to be convinced. You asked what's wrong, I assumed you'd like to know what I think. To me it now looks like you wanted to prove me wrong instead. I summarized plenty of problems, with the biggest one being bad API docs due to lack of detailed arguments and return types description and labeling and bad naming practices in general. FWIW, I've watched 4 hours worth of video on Haskell lens by SPJ and I still don't find the documentation clear. It could simply be that I'm not clever enough. Well written API docs would definitely help with that too though.
- jose_zap 4y ago
  You may use the optics package instead. It is a replacement for the lens octaves with a focus on good docs and better error messages: https://hackage.haskell.org/package/optics-0.1/docs/Optics.html https://hackage.haskell.org/package/optics-0.1/docs/Optics.h...
spion 4y ago
> Right... Like the doc of the regex match function in Rust is useless because it doesn't explain regexes. https://docs.rs/regex/latest/regex/struct.Match.html https://docs.rs/regex/latest/regex/struct.Match.html At least they name their type variables: > The lifetime parameter 't refers to the lifetime of the matched text C# do too: https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginconnect?view=net-6.0#system-net-sockets-socket-beginconnect(system-net-endpoint-system-asynccallback-system-object) https://docs.microsoft.com/en-us/dotnet/api/system.net.socke... - every function argument is named, labelled and described separately.