Update base modules to include descriptions and examples about motoko-base HOT 3 OPEN

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

from motoko-base.

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).

from motoko-base.

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.

from motoko-base.