Meta-Issue: Documentation Burn-down list (DRAFT)

[crusso]

Our documentation is lacking examples for the following features already documented in the language-manual.adoc.
This is a check-list to keep track of what's missing.

• checking of all examples (in progress)
• consistent formatting of all examples using fences of the form

  [source, motoko]
  ----
  

  or

  ....
  ....
  

• option/result/try-catch error handling (Christoph working on it)
• separate section on upgrades, stable variables and system methods (pre/postuprade).
  simple example requiring just stable variables: StableCounter.mo
  advanced example (requiring system methods): StableRegistry.mo
• caller id:
  • on shared functions
  • on actor classes
  • e.g. illustrating both

      shared(msg) Counter {
            pulbic shared(msg1) inc () {
              assert (msg1.caller == msg.caller);
              count := 1;
       }
    

• oneway shared functions (unless we disable those) (e.g. Counter.reset : () -> ())
• scoped awaits (if we want to explain that at all)
• mini ToC for language-manual.adoc
• cross-referencing sections where appropriate (e.g. linking to section on shared when mentioning shared)
• move language-manual up one level (perhaps just using adoc feature to do this?)
• intro to base library
• working with funds/cycles (see doc/attic/funds.adoc for previous version)

[rossberg]

I have a request: can the documentation avoid the overuse of pattern matching and use the form shared(msg) for binding message contexts? I believe that is clearer and avoids the confusion around the use of braces for this, which many seem to conclude are part of the shared syntax, not a pattern.

[crusso]

I have a request: can the documentation avoid the overuse of pattern matching and use the form shared(msg) for binding message contexts? I believe that is clearer and avoids the confusion around the use of braces for this, which many seem to conclude are part of the shared syntax, not a pattern.

why the parens though? And msg or ctxt?

[rossberg]

To be consistent with the (mainstream) style of writing parameters elsewhere.

I'd probably use msg, because msg.caller seems intuitive and matches how it is named in other systems.