ErasureCode: proofread abstract API documentation

* Andreas-Joachim Peters suggests to reduce copies to the minimum. When
  possible the output arguments will just point to the input
  argument. This must be documented as any side effect on the input
  argument may modify the output argument

* Fix typos

* Fix may/could/must/should to better reflect what's mandatory and
  what's not.

* Reword the explanation of minimum_to_decode_with_cost to not suggest
  an implementation. This will need to be revisited anyway, when the
  semantic of the cost is defined.

* Explain chunk size constraints

Signed-off-by: Loic Dachary <loic@dachary.org>
ErasureCode: improve API implementation example

* minimum_to_decode and minimum_to_decode_with_cost are replaced with
  meaningfull examples instead of placeholders

* encode and decode are commented and hard coded constants are replaced
  by defines for readability

* run against valgrind

Signed-off-by: Loic Dachary <loic@dachary.org>
Merge pull request #603 from dachary/wip-erasure-code-example

erasure code example cleanup