Documentation for balances module (#1943)

* comment updates

* added rustdoc and readme

* clarified LockableCurrency trait

* Currency trait rustdocs

* fixed typo

* fixed suggestions round 1

* UpdateBalanceOutcome docs (open for discussion)

* rm description of enum, consolidation, rm ReclaimRebate

* type clarification, examples overhaul, adoc formatting

* adoc to md

* format change for rustdoc

* update links and fix typos

* typos and links

* updates according to comments

* new example

* small clarifications

* trait implementation section

* missing ```

* small changes, ready for review

* line width update

* small tweaks

* Update srml/balances/src/lib.rs

Co-Authored-By: joepetrowski <[email protected]>

* Update srml/balances/src/lib.rs

Co-Authored-By: joepetrowski <[email protected]>

* Update srml/balances/src/lib.rs

Co-Authored-By: joepetrowski <[email protected]>

* Update srml/balances/src/lib.rs

Co-Authored-By: joepetrowski <[email protected]>

* Update lib.rs

* address review by thiolliere

* remove common warning

* Update docs

* updated srml example