Fix RT priority docs (NFC) (#3098)

The ranges and which value was specified as highest were incorrect on
some of them. On Linux, the range is 1 to 99 with 99 being highest.

From `man 7 sched`:
```
Processes scheduled under one of the real-time policies (SCHED_FIFO,
SCHED_RR) have a sched_priority value in the range 1 (low) to 99 (high).
```

Also clean up the relevant javadoc and doxygen comments.

hal/src/main/native/athena/Threads.cpp

@@ -32,8 +32,8 @@ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
     return sch.sched_priority;
   } else {
     *isRealTime = false;
-    // 0 is the only suppored priority for non-realtime, so scale to 1
-    return 1;
+    // 0 is the only supported priority for non-real-time
+    return 0;
   }
 }
 

hal/src/main/native/include/hal/Threads.h

@@ -21,11 +21,13 @@ extern "C" {
 /**
  * Gets the thread priority for the specified thread.
  *
- * @param handle     Native handle pointer to the thread to get the priority for
- * @param isRealTime Set to true if thread is realtime, otherwise false
- * @param status     Error status variable. 0 on success
- * @return           The current thread priority. Scaled 1-99, with 1 being
- * highest.
+ * @param handle     Native handle pointer to the thread to get the priority
+ *                   for.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @param status     Error status variable. 0 on success.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
                               int32_t* status);
@@ -34,23 +36,25 @@ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime,
  * Gets the thread priority for the current thread.
  *
  * @param handle     Native handle pointer to the thread to get the priority for
- * @param isRealTime Set to true if thread is realtime, otherwise false
- * @param status     Error status variable. 0 on success
- * @return           The current thread priority. Scaled 1-99, with 1 being
- * highest.
+ * @param isRealTime Set to true if thread is real-time, otherwise false.
+ * @param status     Error status variable. 0 on success.
+ * @return           The current thread priority. For real-time, this is 1-99
+ *                   with 99 being highest. For non-real-time, this is 0. See
+ *                   "man 7 sched" for details.
  */
 int32_t HAL_GetCurrentThreadPriority(HAL_Bool* isRealTime, int32_t* status);
 
 /**
  * Sets the thread priority for the specified thread.
  *
- * @param thread   Reference to the thread to set the priority of
- * @param realTime Set to true to set a realtime priority, false for standard
- * priority
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- * highest
- * @param status   Error status variable. 0 on success
- * @return         The success state of setting the priority
+ * @param thread   Reference to the thread to set the priority of.
+ * @param realTime Set to true to set a real-time priority, false for standard
+ *                 priority.
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @param status   Error status variable. 0 on success.
+ * @return         True on success.
  */
 HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime,
                                int32_t priority, int32_t* status);
@@ -58,13 +62,14 @@ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime,
 /**
  * Sets the thread priority for the current thread.
  *
- * @param thread   Reference to the thread to set the priority of
- * @param realTime Set to true to set a realtime priority, false for standard
- * priority
- * @param priority Priority to set the thread to. Scaled 1-99, with 1 being
- * highest
- * @param status   Error status variable. 0 on success
- * @return         The success state of setting the priority
+ * @param thread   Reference to the thread to set the priority of.
+ * @param realTime Set to true to set a real-time priority, false for standard
+ *                 priority.
+ * @param priority Priority to set the thread to. For real-time, this is 1-99
+ *                 with 99 being highest. For non-real-time, this is forced to
+ *                 0. See "man 7 sched" for more details.
+ * @param status   Error status variable. 0 on success.
+ * @return         True on success.
  */
 HAL_Bool HAL_SetCurrentThreadPriority(HAL_Bool realTime, int32_t priority,
                                       int32_t* status);