Better Closure Docs

[Android789515]

Related problem

The docs have very little information on each subject. Just one tiny example.

Going through the closures section:

Common commands that can be used with a closure

all
any
collect
do
each
explain
filter
group-by
interleave
items
par-each
reduce
skip until
skip while
take until
tee
update
upsert
zip

None of these methods are explained in further detail. I have no idea what items does, what par-each does, group-by, explain, etc.

Describe the solution you'd like

Document each method as well as possible usages.

Describe alternatives you've considered

No response

Additional context and details

No response

[raoulkent]

I can take a look at this. I will try to add some simple examples but with understandable explanations.

[raoulkent]

I think that the main thing of the page is not to explain how to use each of the listed commands, but rather how they can be used in closures.

I added a few examples in the documentation to exemplify how the closure can be used with 4 different commands.

See #1928

[sholderbach]

Moving over to the website repo as this issue primarily discusses the organization or enhancements to the website/book documentation.

[sholderbach]

I actually kind of disagree with adding this to the Language Reference manual. The purpose of the reference manual primarily is to properly explain each mentioned concept cleanly and correctly and only use examples to explain particular important concepts (e.g. that a closure captures values by value and closes over them so they aren't affect by the outer scope anymore)
Explaining the use of the commands would be better suited to the command reference and generally helpful examples should probably move to the larger book where more than just the core patterns and rules you need to know can be explained. If the reference is long but trivial it defeats the purpose as a quick and useful reference to understand concepts and give a refresher to the intermediate users.

@NotTheDr01ds added those references to commands that interact with certain types from the scope commands set to better build connections and discover concepts worth explaining.

I think in the language reference we should cross link those to the command reference but I would recommend collections of examples to rather be explained in the book or if its just examples (that are helpful) the cookbook

[raoulkent]

@sholderbach That's fair. Would it be better to then link to the book for examples then, and move the examples there?

I'm thinking from the new users perspective, they may not know where to look if different types of information can be found if it's not super clearly specced out early in the discovery process.