Documentation and Samples improvement(s)

[k33g]

WIP

• [ ] Add documentation of https://github.com/eclipse/golo-lang/blob/master/src/main/golo/functions.golo
• [ ] Complement part about Functional Errors https://github.com/eclipse/golo-lang/blob/master/doc/misc.adoc#functional-errors-gololangerrors
• [ ] add more usefull samples for each type
• [ ] Complement part about Asynchronous programming helpers https://github.com/eclipse/golo-lang/blob/master/doc/misc.adoc#asynchronous-programming-helpers-gololangasync
• [ ] add something about promises
• [ ] "human readable" samples
• [ ] Complement part about DynamicVariable https://github.com/eclipse/golo-lang/blob/master/doc/misc.adoc#scala-like-dynamic-variable-gololangdynamicvariable
• [ ] find a use case for "ordinary mortal"
• [ ] ...

⚠️ To my mind Golo documentation shouldn't look like the documentation of Haskell or Scala :stuck_out_tongue_closed_eyes:

❓ I think that Functional Errors and Asynchronous programming helpers deserve their own section (instead being part of "misc modules")

WDYT? @jponge @Artpej @yloiseau and the others

[yloiseau]

I don't get your first point... (see http://golo-lang.org/documentation/next/golodoc/gololang/Functions.html)

[k33g]

@yloiseau yes, but not in the "guide": http://golo-lang.org/documentation/next/index.html

[yloiseau]

I'm not sure that it's relevant to dedicate a guide (sub)section for each and every standard module. I view the guide as a documentation on the language itself, along with the paradigms and spirit, not an extensive documentation. The module documentation is the place to document them (thanks captain obvious!) As an analogy, languages with batteries included (like python or java) don't document every standard module/package, but more the spirit and techniques, and references the API doc. The python documentation is better integrated however, and I indeed think we could work on integrating the guide, golodoc and javadoc in a more homogeneous site/documentation). As for the Function module you mention, it's just a collection of useful function that does not require a explanation in itself, provided the golodoc is well written :wink: , contrary to the error management and asynchronous programing, which are difficult topics in themselves (and actually probably deserve their own section, I agree).

However:

1. several modules documentations can surely be improved
2. we can add sections to the guide, or improve existing ones, on specific topics or paradigms, in the same vain as your #392 and #394 question, but it's more the subject of a «Real World Golo» or «Golo Cookbook» book :smile:

[k33g]

@eclipse/eclipse-golo 👋 I'm testing the notifications to the team. Where to create the Golo Cookbook?