fixup! [Docs] Improve and unify Doxygen comments, part 1

Signed-off-by: Michał Kowalczyk <mkow@invisiblethingslab.com>

Documentation/devel/howto-doc.rst

@@ -159,7 +159,7 @@ Preferred Doxygen style
        * \param  second  Second addend.
        *
        * \returns  Sum of the arguments. Sometimes a longer description is needed,
-       *           then is should be wrapped and aligned like this.
+       *           then it should be wrapped and aligned like this.
        */
       int foo(int first, int second) {
           return first + second;

Pal/src/host/Linux-SGX/enclave_ocalls.c

@@ -88,9 +88,9 @@ static long sgx_exitless_ocall(uint64_t code, void* ms) {
      *   and our enclave thread grabbed lock but it doesn't matter at this point
      *   (OCALL is done, ret == 0, no need to wait on futex)
      * - or OCALL is still pending and the request is still blocked on spinlock
-     *   (OCALL is not done, ret == -EAGAIN, let's wait on futex) */
+     *   (OCALL is not done, ret < 0, let's wait on futex) */
 
-    if (ret == -EAGAIN) {
+    if (ret < 0) {
         /* OCALL takes a lot of time, so fallback to waiting on a futex; at this point we exit
          * enclave to perform syscall; this code is based on Mutex 2 from Futexes are Tricky */
         uint32_t c = SPINLOCK_UNLOCKED;

common/include/spinlock.h

@@ -7,8 +7,6 @@
 #ifndef _SPINLOCK_H
 #define _SPINLOCK_H
 
-#include <errno.h>
-
 #include "api.h"
 #include "cpu.h"
 #include "log.h"
@@ -125,7 +123,7 @@ static inline void spinlock_lock(spinlock_t* lock) {
  * \param  lock        The lock.
  * \param  iterations  Number of iterations (tries) after which this function times out.
  *
- * \returns  0 if acquiring the lock succeeded, -EAGAIN if timed out.
+ * \returns  0 if acquiring the lock succeeded, negative if timed out.
  */
 static inline int spinlock_lock_timeout(spinlock_t* lock, unsigned long iterations) {
     uint32_t val;
@@ -139,7 +137,7 @@ static inline int spinlock_lock_timeout(spinlock_t* lock, unsigned long iteratio
         /* This check imposes no inter-thread ordering, thus does not slow other threads. */
         while (__atomic_load_n(&lock->lock, __ATOMIC_RELAXED) != SPINLOCK_UNLOCKED) {
             if (iterations == 0) {
-                return -EAGAIN;
+                return -1;
             }
             iterations--;
             CPU_RELAX();