doc: Edit the IPM driver APIs

Edit public API details for clarity, grammar, punctuation found
on file ipm.h

Made consistent use of @retval to document return values.

Used imperative verbs for all @brief descriptions.

Change-Id: Ie5516fcb18648a99c58bcfef7888286dead7cff4
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>