Update base modules to include descriptions and examples

[lsgunnlsgunn]

It would be good for all of the base *.mo modules to follow a consistent pattern. I think it would be nice to use a format like this:

• Module-name

• Module-description: At least one sentence but maybe more to describe the module -- maybe even highlighting a few of the most common or unique use cases.

• Function-name

  • Function-description: At least one sentence but maybe more to describe the function purpose -- maybe even highlighting a few of the most common or unique use cases.

  • Function definition (I'm not sure what the proper terminology for this is)

  • Function example (I think this could be the unit test code snippet)

  • Additional remarks/notes, if applicable

I couldn't figure out how to add these additions to the existing code given the current script, but I'm thinking of something like this (warning: fictional content!):

/**
[#mod-Char]
= Char

The `Char` module provides functions for manipulating single character data types in your program.
The module includes functions to evaluate `char` data. 
*/

import Prim "mo:prim";
module {
  public let isDigit : Char -> Bool = func(char) {
    Prim.charToWord32(char) - Prim.charToWord32('0') <= (9 : Word32)
  };
/* 
Evaluates a character and returns True if the 
character is a numeric digit, or False if it not.
*/
}
/* 
Insert isDigit test / example code 
*/

I'm happy to take a stab at the first part with the module name and description, but I'm not sure how/where to put the additional sections that I think would make the library feel more complete.

[nomeata]

@kritzcreek , how does your work on from dfinity/motoko#1536 affect this?

[nomeata]

Function definition (I'm not sure what the proper terminology for this is)

You probablay mean “Function declaration” – we want the function name and type in the docs, but not the actual function body (that would be the function definition).

[nomeata]

Doesn't src/List.mo already follow that pattern? Note that the current tool automatically inserts section headings and the function’s type for each function (as seen in the output at https://sdk.dfinity.org/docs/base-libraries/list).

Ok, granted, no examples in that file yet, but you can just put them in the documentation comment before each function, using normal asciidoc syntax.