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

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.

[x] checking of all examples (in progress)
[x] consistent formatting of all examples using fences of the form
```
[source, motoko]
----
```
or
```
....
....
```
[x] option/result/try-catch error handling (Christoph working on it)
[x] 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

[x] 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;
   }

[x] oneway shared functions (unless we disable those) (e.g. Counter.reset : () -> ())
[x] 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)
[x] move language-manual up one level (perhaps just using adoc feature to do this?)
[x] intro to base library
[x] working with funds/cycles (see doc/attic/funds.adoc for previous version)

Oct 27 '20 20:10 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.

Oct 28 '20 06:10 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.

why the parens though? And msg or ctxt?

Oct 28 '20 10:10 crusso

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.

Oct 28 '20 14:10 rossberg

This issue is probably long outdated with all of the documentation revamps that have happened in the last 5 years. Anything worth keeping this open for here @crusso?

Apr 15 '25 07:04 christoph-dfinity