Haskell: add in-code comments

[lsmor]

Hi @alexjercan (pinging you as you are in the CODEOWNERS for haskell. Correct me if I am wrong)

First. Congratulations! having different Lexer is a good way to show different Haskell techniques. I'd suggest to add coments in all files explaining a little bit what's going on. I know the readme already does this (and It does it very good), but having a more in-code comments could help. For example

LParens <$ advance -- This is criptic for someone not knowing haskell...

Moreover, having different lexer can lead to confusion, so It would be nice to have a big comment at the beginning of the file explaining the technique in used. Also, pointing out that some of them are not the "idiomatic"/"strongest" way of doing the job. For example, the Basic.hs lexer is very simple but using in real-world Parsec.hs or State.hs are the actual idiomatic implementations of the lexer.

So I propose, for each file:

• Add a hearder comment explaining the technique
• If the lexer is not Parsec.hs or State.hs add a disclaimer in such a header like "This is not the most convinient way"
• For every function using creepy symbols like <*>, <$, ... add a line comment explaining what it means (roughly)
• A few more comments for unusual things, like using "prime" for variable names like (lexer, lexer', lexer'', etc...)

Are you ok if I do it and you (or other person) review it?, do you prefer to do it yourself, or not do it at all?

Thanks

[alexjercan]

Hi @lsmor, I think you made a good point. Feel free to do it :100: