Motoko documentation - opportunity to strengthen

Recent documentation improvements have been fantastic to see. I think there is a need to make the documentation sufficient to help developers without having to parse throught the Motoko Types Base source code.

Suggestion #1: HashMaps - it would be very useful to include an example of how to instantiate the class because the documentation as currently written requires consulting the

The page Hashmap states, “The class is parameterized by the key’s equality and hash functions, and an initial capacity.”. In order to understand how to do this one then needs to consult to look at the formal class definition. While there are examples with Hashmaps, the Motoko base documentation should be sufficient to stand on its own.

Why not just include an example like:

let phonebook = Map.HashMap<Name, Entry>(0, Text.equal, Text.hash);

The actual parameters are not in the same order as in the Motoko documentation. This should be corrected.

Suggestion #2 - Provide examples of all the functions. The base library functions should include an example of how to call each and every function. Different languages uses different notations. Developers may not familiar with the grammar and having an example augments the formal definitions.

These examples should work in the Motoko Playground - I do not think debug statements work in the Playground, so something like this would help new developers understand::

// Playground demo of all Int functions

import Int “mo:base/Int”;

actor Test {
var w = 3 : Int;
var x = 0 : Int;
var y = 100 : Int;
var z = -50 : Int;

public query func demo_abs() : async Int {
//Returns the absolute value of the number
return Int.abs(z);

public query func demo_toText() : async Text {
//Conversion to Text
return Int.toText(y);

public query func demo_min() : async Int {
//Returns the minimum of x and y.
return Int.min(z,y);

public query func demo_max() : async Int {
//Returns the maximum of x and y.
return Int.max(z,y);

public query func demo_equal() : async Bool {
//Returns x == y.
return Int.equal(z,y);
public query func demo_notequal() : async Bool {
//Returns x != y.
return Int.notEqual(z,y);
public query func demo_less() : async Bool {
//Returns x < y.
return Int.less(z,y);
public query func demo_greater() : async Bool {
//Returns x > y.
return Int.greater(z,y);
public query func demo_greaterOrEqual() : async Bool {
//Returns x >= y.
return Int.greaterOrEqual(z,y);
public query func demo_compare() : async {#less; #equal; #greater} {
//Returns the order of x and y.
public query func demo_neq() : async Int {
//Returns the negation of x, -x .
return Int.neq(y);
public query func demo_add() : async Int {
//Returns the sum of x and y, x + y.
return Int.add(y,z);
public query func demo_sub() : async Int {
//Returns the difference of x and y, x - y.
return Int.sub(y,z);
public query func demo_mul() : async Int {
//Returns the product of x and y, x * y.
return Int.mul(y,z);
public query func demo_div() : async Int {
//Returns the division of x by y, x / y. Traps when y is zero.
return Int.div(y,z);
public query func demo_rem() : async Int {
//Returns the remainder of x divided by y, x % y. Traps when y is zero.
return Int.rem(y,z);
public query func demo_pow() : async Int {
//eturns x to the power of y, x ** y.
return Int.pow(y,w);



These examples are not the worst examples of method implementation… Hashmap, array and iter drove me crazy. :exploding_head:
We really need one example for each method in the doc. Something like Svelte tutorial on their official website. Not everyone is an engineer… Some people like me have only a normal intelligence. :sweat_smile:


All good suggestions. We are heavily reworking the base library and associated docs:

  • All Collections will have a consistent interface
  • We will have a default easy to use vector and map classes
  • Documentation will have examples and better explanations (like Buffer but even better)

We will have an announcement soon.


I was willing to start the Society for Hashmap, Array and Iter Survivors.
I totally agree!


Fantastic news. This will greatly help.

1 Like