Meta: Documentation issue tracking

[matthewhammer]

The base library varies in its level of completion with respect to both functionality and documentation of functionality. Completing both is important, but requires immense efforts.

This issue only focuses on the completion of documentation (not features to be documented), and prioritizes modules based on our impressions of how much they are used and how much their currently-lacking documentation is affecting Motoko programmers' productivity and happiness.

As a coarse-grained category system, we look at three levels of completion for each module:

1. every function or method has an English description as a complete sentence (or several).
2. some functions (important ones, or confusing ones) have examples
3. every function has at least one runnable example that uses it
4. the module is used in one or several deployed applications that is open source, showcasing its use in a real system.

Some modules are more obscure than others.

For those that are not obscure, we want to work towards level 3 for them in the short term, with issues tracked here, so that every function has an example in the documentation of how to use it. (More obscure modules also deserve examples, but should take less priority.)

List of "high-priority" modules and the next level to which they aspire (alphabetical):

• Array. 3
• Buffer. 2
• Debug. 2
• Hash. 1
• HashMap. 1
• Heap. 2
• Iter. 3
• List. 2
• Nat. 2.
• Option. 3
• Principal. 1
• Random. 2
• Text. 2
• Time. 2
• Trie. 2