4 ms·

> 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

> 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.
- axman6 4y ago
  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 4y ago
    There are ways of making your point that wouldn't descend into personal attacks. Please don't give Haskellers a bad reputation!
    - spion 4y ago
      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 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.

axman6 4y ago
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 4y ago
  There are ways of making your point that wouldn't descend into personal attacks. Please don't give Haskellers a bad reputation!
  - spion 4y ago
    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.