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 Hashmap.mo.
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 Hashmap.mo 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.
return Int.compare(z,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);
};
};
