[Haskell-cafe] Getting some funny brackets in Haddock docs

[Matt Renaud]

Thanks for the input Steven! We did what you mentioned (adding a tip about
Overloaded lists near the top) in the containers introduction and
walkthrough at https://haskell-containers.readthedocs.io/en/latest/set.
html#short-example. It sounds like we should do the same thing in the
Haddocks.

I'm also in agreeance that the examples should be copy-pasteable into
Haskell source files or the repl. I think what Michael suggested (moving
the set/map/sequence construction to a line above and assigning it to a
variable) is a good compromise; there's no special syntax added and the
actual use of the function becomes less "noisy".

On Wed, Jan 10, 2018, 7:24 AM Steven Leiva <leiva.steven at gmail.com> wrote:

> I consider myself a Haskell beginner, and I think that the current
> situation (with the use of *fromList*) will be less confusing than the
> funny brackets.
>
> Even if you could make it so that copy/past would turn funny brackets into
> fromList, it would still be surprising behavior. When the code does
> something unexpected, we are going to try to put in the funny brackets in
> the repl. (Maybe that's more for programming beginners versus Haskell
> beginners, but let's not discount them either).
>
> I haven't read the docs, and I understand that your primary concern is the
> noise from *fromList*, but I think leaving things as is and adding some
> wording that says "Hey, if you want to avoid having *fromList* everywhere
> in your own code, you can add OverloadedList  extension" would be the most
> approachable. (Shouldn't be too much to ask a beginner to at least read the
> preamble of a module's docs).
>
> Just my 2 cents.
>
> On Wed, Jan 10, 2018 at 5:50 AM, Johannes Waldmann <
> johannes.waldmann at htwk-leipzig.de> wrote:
>
>> Hi,
>>
>> > It looks like you're saying that `M.size [(2,3)]` should not be 1 (but
>> > I'm not sure).
>>
>> Sorry for being terse.
>> No, that was just a comment about syntax, not semantics.
>>
>> I was just stating that because of the IsList instance,
>> we can write  [(2,3)]  instead of  M.fromList [(2,3)]
>>
>> This would give shorter text in the examples in the API doc -
>> and has the immense benefit that it already works as-is,
>> does not need any haddock changes, unicodes, JS, etc.
>>
>> But it would hide the type distinction (Map vs. List)
>> so it might turn out to be unhelpful.
>>
>> - J
>> _______________________________________________
>> Haskell-Cafe mailing list
>> To (un)subscribe, modify options or view archives go to:
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
>> Only members subscribed via the mailman list are allowed to post.
>>
>
>
>
> --
> Steven Leiva
> 305.528.6038 <(305)%20528-6038>
> leiva.steven at gmail.com
> http://www.linkedin.com/in/stevenleiva
> _______________________________________________
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20180110/c9498323/attachment.html>