Improve flattener documentation

[wachulski]

As of now the flattener documentation is scarce:

Specifically it does not say:

• what it does
• what the limitations are

Let's improve the docs for this feature. Compare with https://www.npmjs.com/package/truffle-flattener

Inspiration may be taken from: https://github.com/EthWorks/Waffle/blob/master/waffle-compiler/test/flattener/flattener.ts