From 8496f3687919e081f3648534cef7f000d4723ed4 Mon Sep 17 00:00:00 2001
From: fincs <fincs.alt1@gmail.com>
Date: Sun, 28 Jan 2018 18:34:08 +0100
Subject: [PATCH] Documentation: address first batch of comments (in #38)

---
 nx/include/switch/arm/cache.h     | 4 ++++
 nx/include/switch/ipc.h           | 5 +----
 nx/include/switch/kernel/detect.h | 4 ++--
 nx/include/switch/kernel/mutex.h  | 2 ++
 nx/include/switch/runtime/env.h   | 2 +-
 5 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/nx/include/switch/arm/cache.h b/nx/include/switch/arm/cache.h
index 5cab03ee..a97fbbed 100644
--- a/nx/include/switch/arm/cache.h
+++ b/nx/include/switch/arm/cache.h
@@ -12,6 +12,7 @@
  * @param addr Address of the buffer.
  * @param size Size of the buffer, in bytes.
  * @remarks Cache flush is defined as Clean + Invalidate.
+ * @note The start and end addresses of the buffer are forcibly rounded to cache line boundaries (read from CTR_EL0 system register).
  */
 void armDCacheFlush(void* addr, size_t size);
 
@@ -19,6 +20,7 @@ void armDCacheFlush(void* addr, size_t size);
  * @brief Performs a data cache clean on the specified buffer.
  * @param addr Address of the buffer.
  * @param size Size of the buffer, in bytes.
+ * @note The start and end addresses of the buffer are forcibly rounded to cache line boundaries (read from CTR_EL0 system register).
  */
 void armDCacheClean(void* addr, size_t size);
 
@@ -26,6 +28,7 @@ void armDCacheClean(void* addr, size_t size);
  * @brief Performs an instruction cache invalidation clean on the specified buffer.
  * @param addr Address of the buffer.
  * @param size Size of the buffer, in bytes.
+ * @note The start and end addresses of the buffer are forcibly rounded to cache line boundaries (read from CTR_EL0 system register).
  */
 void armICacheInvalidate(void* addr, size_t size);
 
@@ -33,5 +36,6 @@ void armICacheInvalidate(void* addr, size_t size);
  * @brief Performs a data cache zeroing operation on the specified buffer.
  * @param addr Address of the buffer.
  * @param size Size of the buffer, in bytes.
+ * @note The start and end addresses of the buffer are forcibly rounded to cache line boundaries (read from CTR_EL0 system register).
  */
 void armDCacheZero(void* addr, size_t size);
diff --git a/nx/include/switch/ipc.h b/nx/include/switch/ipc.h
index ffd1b4a5..5fa1b0e1 100644
--- a/nx/include/switch/ipc.h
+++ b/nx/include/switch/ipc.h
@@ -57,10 +57,7 @@ static inline void ipcInitialize(IpcCommand* cmd) {
     cmd->NumHandlesMove = 0;
 }
 
-/**
- * @brief IPC buffer descriptor.
- * @todo Make sure sizeof isn't 16 bytes!
- */
+/// IPC buffer descriptor.
 typedef struct {
     u32 Size;   ///< Size of the buffer.
     u32 Addr;   ///< Lower 32-bits of the address of the buffer
diff --git a/nx/include/switch/kernel/detect.h b/nx/include/switch/kernel/detect.h
index 92051f64..2c5ee370 100644
--- a/nx/include/switch/kernel/detect.h
+++ b/nx/include/switch/kernel/detect.h
@@ -11,7 +11,7 @@
 bool kernelAbove200(void);
 /// Returns true if the kernel version is equal to or above 3.0.0.
 bool kernelAbove300(void);
-/// Returns true if the kernel version is equal to or above 2.0.0.
+/// Returns true if the kernel version is equal to or above 4.0.0.
 bool kernelAbove400(void);
-/// Returns true if code is running under a debugger.
+/// Returns true if the process has a debugger attached.
 bool detectDebugger(void);
diff --git a/nx/include/switch/kernel/mutex.h b/nx/include/switch/kernel/mutex.h
index 1cc1b0b0..bdad14af 100644
--- a/nx/include/switch/kernel/mutex.h
+++ b/nx/include/switch/kernel/mutex.h
@@ -16,6 +16,7 @@ typedef _LOCK_RECURSIVE_T RMutex;
 /**
  * @brief Initializes a mutex.
  * @param m Mutex object.
+ * @note A mutex can also be statically initialized by assigning 0 to it.
  */
 static inline void mutexInit(Mutex* m)
 {
@@ -37,6 +38,7 @@ void mutexUnlock(Mutex* m);
 /**
  * @brief Initializes a recursive mutex.
  * @param m Recursive mutex object.
+ * @note A recursive mutex can also be statically initialized by assigning {0,0,0} to it.
  */
 static inline void rmutexInit(RMutex* m)
 {
diff --git a/nx/include/switch/runtime/env.h b/nx/include/switch/runtime/env.h
index 89ac36ae..66c0d0b9 100644
--- a/nx/include/switch/runtime/env.h
+++ b/nx/include/switch/runtime/env.h
@@ -39,7 +39,7 @@ enum {
 typedef void NORETURN (*LoaderReturnFn)(int result_code);
 
 /**
- * @brief Sets up the homebrew environment (internally called).
+ * @brief Parses the homebrew loader environment block (internally called).
  * @param ctx Reserved.
  * @param main_thread Reserved.
  * @param saved_lr Reserved.