Correct the absorptivity docstring

The terminology was confusing and also the math markup didn't
work.
Update coroutine docs to be readable and complete

Some docstrings were missing and there was the
foo(*args, **kwargs) problem because of the coroutine
wrapper. Also moved the consumer to the last position
by filters.
Split coroutine docs into user and devel part
Merge pull request #161 from ufo-kit/coroutines-docs-refactoring

Coroutines docs refactoring