Fix markup errors in and add to Sound.Tidal.UI documentation.

[patrickt]

Hey, folks 👋🏻 I’ve been really loving my TidalCycles experience, and wanted to give something back. Since I’m an experienced Haskeller, I tend to use the Haddocks as my primary source of truth, so I’d like to give them a little more love and port over/write documentation when necessary.

This patch:

• adds a module header that appears in the Haddocks;
• ports function descriptions and examples from the main reference documentation;
• explicates undocumented functions (the ones I could figure out, anyway);
• engages in minimal reordering of functions for consistency's sake (see the commentary below about explicit export lists for an alternative to this);
• fixes a lot of errors resulting from Markdown/Haddock inconsistencies;
• fixes type errors in example code.

There should be no observable change in behavior, as no code has actually changed. I hope to have time to renovate some of the other modules.

Other things I could have done to this module, and would be happy to do now or in a follow-up patch:

• setting an explicit export list (this would be more work, but would also allow me to customize the order of appearance without actually having to move them in the source);
• marking deprecated functions/aliases as {-# DEPRECATED #-}, possibly setting the stage for their removal

[patrickt]

Here is a PDF of what the documentation looks like with this patch: Sound.Tidal.UI.pdf.

[patrickt]

Would a maintainer mind approving the workflows here so this can go green?

[matthewkaney]

Thank you so much for this! I'm interested in more overlap between the Haddock docs and the tidalcycles.org docs, so this is a great step in that direction.

(As an aside, I see you're in Queens—if you haven't done anything with livecode.nyc, you totally should!)

[matthewkaney]

I'd always assumed that the underscore variants were essentially internal implementations and not intended for public use. If that's the case, then we shouldn't be encouraging their use, and should eventually exclude them from export lists. @yaxu, is that right, or am I wrong and these variants should be considered part of the public API?

Are there cases where you've run into ambiguous type errors?

[patrickt]

If memory serves, I once had enabled perhaps too many {-# LANGUAGE #-} pragmas in the Tidal REPL and got out of it by using an underscore variant. I’m happy to elide this section and just replace it with “the underscore variants are private,” if @yaxu thinks that’s appropriate.

[yaxu]

Hm well I think they shouldn't be totally private, as they're useful in writing custom functions. I would say something like, the underscore variants generally only accept plain values and not patterns apart from their final argument, and are intended mainly for those developing or extending tidal.

[patrickt]

@yaxu Gotcha. I’ve changed the wording to reflect this.

[yaxu]

Thanks for this and apologies for the long delay !