doc: API edits for microkernel semaphore.h
doc: API edits for microkernel semaphore.h

Review and edit API notes for punctuation and to make explanations about
conditional routines the same throughout microkernel APIs.

Made consistent use of @retval to document return values.

Used imperative verbs for all @brief descriptions.

Change-Id: I2da0ea869151f3bdd5846f86d31dfd899e1ca1fc
Signed-off-by: Rodrigo Caballero <e74c61adb7ade025bc8e83a25052d36636c989a9@intel.com>

zephyriot/zephyr,zephyrproject-rtos/zephyr,rsalveti/zephyr,sharronliu/zephyr,erwango/zephyr,mirzak/zephyr-os,punitvara/zephyr,coldnew/zephyr-project-fork,pklazy/zephyr,pklazy/zephyr,fractalclone/zephyr-riscv,GiulianoFranchetto/zephyr,bboozzoo/zephyr,ldts/zephyr,aceofall/zephyr-iotos,rsalveti/zephyr,nashif/zephyr,rsalveti/zephyr,ldts/zephyr,Vudentz/zephyr,zephyrproject-rtos/zephyr,aceofall/zephyr-iotos,nashif/zephyr,ldts/zephyr,zephyriot/zephyr,explora26/zephyr,runchip/zephyr-cc3220,tidyjiang8/zephyr-doc,bigdinotech/zephyr,fbsder/zephyr,coldnew/zephyr-project-fork,bigdinotech/zephyr,runchip/zephyr-cc3220,finikorg/zephyr,runchip/zephyr-cc3220,coldnew/zephyr-project-fork,zephyrproject-rtos/zephyr,GiulianoFranchetto/zephyr,Vudentz/zephyr,Vudentz/zephyr,32bitmicro/zephyr,erwango/zephyr,coldnew/zephyr-project-fork,kraj/zephyr,runchip/zephyr-cc3200,holtmann/zephyr,tidyjiang8/zephyr-doc,bboozzoo/zephyr,fractalclone/zephyr-riscv,nashif/zephyr,32bitmicro/zephyr,32bitmicro/zephyr,bigdinotech/zephyr,zephyriot/zephyr,explora26/zephyr,holtmann/zephyr,sharronliu/zephyr,galak/zephyr,punitvara/zephyr,fractalclone/zephyr-riscv,galak/zephyr,kraj/zephyr,Vudentz/zephyr,rsalveti/zephyr,mirzak/zephyr-os,rsalveti/zephyr,Vudentz/zephyr,fbsder/zephyr,explora26/zephyr,mbolivar/zephyr,coldnew/zephyr-project-fork,sharronliu/zephyr,zephyrproject-rtos/zephyr,runchip/zephyr-cc3200,runchip/zephyr-cc3220,bboozzoo/zephyr,finikorg/zephyr,mbolivar/zephyr,nashif/zephyr,GiulianoFranchetto/zephyr,galak/zephyr,pklazy/zephyr,tidyjiang8/zephyr-doc,GiulianoFranchetto/zephyr,finikorg/zephyr,bigdinotech/zephyr,nashif/zephyr,tidyjiang8/zephyr-doc,bboozzoo/zephyr,kraj/zephyr,punitvara/zephyr,finikorg/zephyr,ldts/zephyr,holtmann/zephyr,ldts/zephyr,galak/zephyr,sharronliu/zephyr,aceofall/zephyr-iotos,erwango/zephyr,aceofall/zephyr-iotos,fbsder/zephyr,sharronliu/zephyr,zephyriot/zephyr,galak/zephyr,erwango/zephyr,zephyriot/zephyr,fractalclone/zephyr-riscv,explora26/zephyr,pklazy/zephyr,punitvara/zephyr,runchip/zephyr-cc3200,bboozzoo/zephyr,erwango/zephyr,finikorg/zephyr,fractalclone/zephyr-riscv,mirzak/zephyr-os,32bitmicro/zephyr,32bitmicro/zephyr,mbolivar/zephyr,explora26/zephyr,mirzak/zephyr-os,aceofall/zephyr-iotos,tidyjiang8/zephyr-doc,holtmann/zephyr,runchip/zephyr-cc3200,kraj/zephyr,runchip/zephyr-cc3220,mirzak/zephyr-os,Vudentz/zephyr,zephyrproject-rtos/zephyr,holtmann/zephyr,fbsder/zephyr,bigdinotech/zephyr,mbolivar/zephyr,pklazy/zephyr,kraj/zephyr,runchip/zephyr-cc3200,punitvara/zephyr,mbolivar/zephyr,fbsder/zephyr,GiulianoFranchetto/zephyr