News for hackers. Stuff that matters.
Re:Dhall: A Gateway Drug to Haskell by fn-mote on Tuesday June 07, 2022 @06:49PM (#31660967)
All of my sibling posts: please be specific!! Somebody not at your level (and there's more for Haskell than more mainstream languages)... like me... isn't going to get what you're talking about.

> And if you won't learn the hard idioms at all ... you will never get most of the value.

Ok... mention a hard idiom? Even if you don't want to go into detail. We'll look it up.

> [...] reading someone else's Haskell code insanely difficult.

I'm wondering if that's because they used a ton of operators like (.)(.)(.) or :=-=: (just made that up, i hope), or was it because of some deeper reason like too much magic hidden in the monad transformers. Anything concrete you're willing to say will clear some of this haze of non-understanding.

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @07:18PM (#31661231)
Ok, lets be specific. Lets write a comment to explain this function:

https://github.com/dhall-lang/dhall-haskell/blob/master/dhal...

Re:Dhall: A Gateway Drug to Haskell by rowanG077 on Tuesday June 07, 2022 @07:59PM (#31661570)
There is already a comment there? And the implementation doesn't look too hard. I don't feel like this is an example of a hard to understand Haskell function.
Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:23PM (#31661715)
How about you try your best to explain all of it? What exactly is that you understand here? What does Optics.rewriteOf do? What's the purpose of Lint.useToMap? How about D.subExpressions ? How does that composition work with the loop function?

Even better. How would you go about finding the source code containing the definition of the function `D.subExpressions` ?

Re:Dhall: A Gateway Drug to Haskell by rowanG077 on Tuesday June 07, 2022 @08:40PM (#31661846)
No I didn't understand every sub-function in this function. That isn't necessary to get an idea of what a function does. All of your questions can be answered incredible quickly though using https://hoogle.haskell.org/

> What does Optics.rewriteOf do?

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

> What's the purpose of Lint.useToMap?

Hoogle again shows https://hackage.haskell.org/package/dhall-1.41.1/docs/Dhall-.... If your function is not indexed you can look at what is qualified as `Lint` and look it up that way.

> How about D.subExpressions ? How does that composition work with the loop function?

https://hackage.haskell.org/package/dhall-1.41.1/docs/Dhall-... All nicely documented... I'm not sure what you mean by composition with the loop function. First the loop function is executed and then afterwards over the result the expression in the first argument to fmap is applied. There is no weird interaction going on here. It's just run this over the result of the loop function if it didn't produce an error.

> Even better. How would you go about finding the source code containing the definition of the function `D.subExpressions` ?

Use hoogle or just look at the imports at the top of the file. Just like any other programming language. Or even better, use the language server to find it for you. For example there is an import here:

`import qualified Dhall.Core as D`

Now you know that function is in the `Dhal.Core` module. Going to that module you see the function is not actually there but is exported from the `Dhal.Syntax` module. It took me literally 5 seconds to find it: https://github.com/dhall-lang/dhall-haskell/blob/master/dhal...

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:44PM (#31661868)
> Hoogling show this is an alias of 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?

Re:Dhall: A Gateway Drug to Haskell by rowanG077 on Tuesday June 07, 2022 @08:49PM (#31661896)
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

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.

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:57PM (#31661962)
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-...)

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

Re:Dhall: A Gateway Drug to Haskell by rowanG077 on Wednesday June 08, 2022 @01:11AM (#31663473)
> 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

Or the C# beginSocketfunction because it doesn't explain what TCP is. 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

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.

Re:Dhall: A Gateway Drug to Haskell by spion on Wednesday June 08, 2022 @09:55AM (#31667394)
> 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

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.socke... - every function argument is named, labelled and described separately.

Re:Dhall: A Gateway Drug to Haskell by axman6 on Sunday June 19, 2022 @11:51AM (#31800451)
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.

Re:Dhall: A Gateway Drug to Haskell by tome on Sunday June 19, 2022 @01:49PM (#31801611)
There are ways of making your point that wouldn't descend into personal attacks. Please don't give Haskellers a bad reputation!
Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 21, 2022 @07:23PM (#31830273)
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.
Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 21, 2022 @06:49PM (#31829997)
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.

Re:Dhall: A Gateway Drug to Haskell by spion on Wednesday June 08, 2022 @09:16AM (#31666843)
> 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.

Re:Dhall: A Gateway Drug to Haskell by jose_zap on Wednesday June 08, 2022 @12:10PM (#31669495)
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.h...

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @09:15PM (#31662103)
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".

Re:Dhall: A Gateway Drug to Haskell by Karrot_Kream on Tuesday June 07, 2022 @09:32PM (#31662236)
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.
Re:Dhall: A Gateway Drug to Haskell by axman6 on Sunday June 19, 2022 @11:54AM (#31800489)
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.
Re:Dhall: A Gateway Drug to Haskell by solomonb on Wednesday June 08, 2022 @12:01AM (#31663039)
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.
Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:46PM (#31661884)
Oh the documentation of Setter is fun:

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.

Re:Dhall: A Gateway Drug to Haskell by axman6 on Sunday June 19, 2022 @12:05PM (#31800583)
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__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.

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 21, 2022 @07:29PM (#31830323)
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.

Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:42PM (#31661856)
The density of that code is just insanely high. In most language that single fmap line would likely be at least 5 lines of code with lots of variable names to aid in understanding. The map rewrite traversal and actual "compiler" loop part would be separated for sure, and `(D.alphaNormalize (D.normalize expressionType))` would be assigned to another intermediate variable as a "preprocessing step"
Re:Dhall: A Gateway Drug to Haskell by spion on Tuesday June 07, 2022 @08:55PM (#31661941)
Here is the documentation I would write for a function like this, in a normal language:

  {-| Given `Conversion` options and a Dhall type `ExprX`, 
      try to convert the JSON value `Value` to a Dhall expression of the specified type. 

      Additionally, if the conversion is successful, apply a rewrite on all maps in the key-value map pair format to map nodes 
      (i.e.  `[{ mapKey = "foo", mapValue = 1 }] -> toMap {foo = 1}`) -}
And here is how I would decompose the first part

  dhallFromJSON (Conversion {..}) expressionType value = do
    let normalizedType = D.alphaNormalize (D.normalize expressionType)
    dhallExpression <- loop [] normalizedType value
    -- Rewrite maps
    return $ Optics.rewriteOf D.subExpressions Lint.useToMap dhallExpression
Re:Dhall: A Gateway Drug to Haskell by lolinder on Tuesday June 07, 2022 @09:57PM (#31662359)
Apologies in advance for the meta comment, but: could you just reply to the comments you're replying to, instead of their parent? Trying to find the context for your quote extracts is more difficult than it needs to be.