Doc: replace non-existing \param command with \a

Rewrite the paragraphs to use the common style and
proper punctuation.

Change-Id: I56fbf5b2e5b9ec5baba8f74783d3b70354900e13
Reviewed-by: Thomas Hartmann <Thomas.Hartmann@digia.com>