Improve the documentation of makeup combinators

[tmbb]

There are two places where we can add this documentation:

• The @doc attributes of the function themselves
• The CONTRIBUTING.md file

These different places might call for different styles of documentation.

[tmbb]

This has been much improved but could be improved even more, this issue will continue open for some time.

[kianmeng]

@tmbb Is this still relevant today? Are there anything else needed?