kernel: add emphasis to nano_sem_take/k_sem_take return code difference

The reversal of the meaning of a value of 0 from k_sem_take vs
nano_sem_take has caused some issue when porting code from the legacy
API to the new API, so put some emphasis on this difference.

- Add a note in the API description.
- Put the call to k_sem_take and the reversal of the return value inside
  of nano_sem_take on one line so that grepping on it shows the
  reversal.

Change-Id: I2f4ba58dc087176d68b55371fa6e367b72559e70
Signed-off-by: Benjamin Walsh <benjamin.walsh@windriver.com>