Index: /trunk/include/iprt/system.h
===================================================================
--- /trunk/include/iprt/system.h	(revision 9934)
+++ /trunk/include/iprt/system.h	(revision 9935)
@@ -34,8 +34,28 @@
 #include <iprt/types.h>
 
-#define IPRT_USAGE_MULTIPLIER UINT64_C(1000000000)
+#define IPRT_USAGE_MULTIPLIER   UINT64_C(1000000000)
 
-/* This structure holds both computed and raw values of overall CPU load counters. */
-typedef struct
+/**
+ * This structure holds both computed and raw values of overall CPU load counters.
+ *
+ * @todo r=bird: What does these values mean?
+ *
+ *               Also, I no longer use 'u32', 'u16', 'u8', 'u64', etc unless this information
+ *               is really important for the user. So, unless there is a better prefix just
+ *               stick to 'u' here.
+ *
+ *               The name of the struct should include the prefix or a shortened
+ *               version of it: RTSYSCPUUSAGESTATS
+ *
+ *               Also, I'd sugest calling it RTSYSCPULOADSTATS, replacing 'usage' with 'load',
+ *               no particular reason, other than that it is easier to read in the (silly)
+ *               condensed form we use for typedefs here.
+ *
+ *               Finally, I'm wondering how portable this is. I'd like to see what APIs are
+ *               available on the important systems (Windows, Solaris, Linux) and compare
+ *               the kind of info they return. This should be done in the defect *before*
+ *               any of the above, please.
+ */
+typedef struct RTSYSCPUUSAGESTATS
 {
     uint32_t u32User;
@@ -74,4 +94,6 @@
  *
  * @returns Number of logical processors in the system.
+ *
+ * @todo Replaced by RTMpGetOnlineCount / RTMpGetCount, retire this guy.
  */
 RTDECL(unsigned) RTSystemProcessorGetCount(void);
@@ -81,4 +103,6 @@
  *
  * @returns Active logical processor mask. (bit 0 == logical cpu 0)
+ *
+ * @todo Replaced by RTMpGetOnlineSet, retire this guy.
  */
 RTDECL(uint64_t) RTSystemProcessorGetActiveMask(void);
@@ -86,15 +110,16 @@
 /**
  * Gets the current figures of overall system processor usage.
- *  
- * @remarks To get meaningful stats this function has to be 
+ *
+ * @remarks To get meaningful stats this function has to be
  *          called twice with a bit of delay between calls. This
  *          is due to the fact that at least two samples of
  *          system usage stats are needed to calculate the load.
- *  
+ *
  * @returns IPRT status code.
- * @param   pStats  Pointer to the structure that contains the 
+ * @param   pStats  Pointer to the structure that contains the
  *                  results. Note that this structure is
  *                  modified with each call to this function and
  *                  is used to provide both in and out values.
+ * @todo r=bird: Change to RTSystemGetCpuLoadStats.
  */
 RTDECL(int) RTSystemProcessorGetUsageStats(PRTCPUUSAGESTATS pStats);
@@ -102,19 +127,20 @@
 /**
  * Gets the current processor usage for a partucilar process.
- *  
- * @remarks To get meaningful stats this function has to be 
+ *
+ * @remarks To get meaningful stats this function has to be
  *          called twice with a bit of delay between calls. This
  *          is due to the fact that at least two samples of
  *          system usage stats are needed to calculate the load.
- *  
+ *
  * @returns IPRT status code.
- * @param   pid     VM process id. 
- * @param   pStats  Pointer to the structure that contains the 
+ * @param   pid     VM process id.
+ * @param   pStats  Pointer to the structure that contains the
  *                  results. Note that this structure is
  *                  modified with each call to this function and
  *                  is used to provide both in and out values.
- *  
- * @todo    Perharps this function should be moved somewhere 
+ *
+ * @todo    Perharps this function should be moved somewhere
  *          else.
+ * @todo    r=bird: Yes is should, iprt/proc.h. RTProcGetCpuLoadStats.
  */
 RTDECL(int) RTProcessGetProcessorUsageStats(RTPROCESS pid, PRTPROCCPUUSAGESTATS pStats);
Index: /trunk/src/VBox/Runtime/r3/posix/system-posix.cpp
===================================================================
--- /trunk/src/VBox/Runtime/r3/posix/system-posix.cpp	(revision 9934)
+++ /trunk/src/VBox/Runtime/r3/posix/system-posix.cpp	(revision 9935)
@@ -94,14 +94,15 @@
 /**
  * Gets the current figures of overall system processor usage.
- *  
- * @remarks To get meaningful stats this function has to be 
+ *
+ * @remarks To get meaningful stats this function has to be
  *          called twice with a bit of delay between calls. This
  *          is due to the fact that at least two samples of
  *          system usage stats are needed to calculate the load.
- *  
+ *
  * @returns None.
  */
 RTDECL(int) RTSystemProcessorGetUsageStats(PRTCPUUSAGESTATS pStats)
 {
+/** @todo r=bird: This is Linux specific and doesn't belong here. Move this to r3/linux/RTSystemGetCpuLoadStats-linux.cpp. */
     int rc = VINF_SUCCESS;
     uint32_t u32UserNow, u32NiceNow, u32SystemNow, u32IdleNow;
@@ -139,10 +140,10 @@
 /**
  * Gets the current processor usage for a partucilar process.
- *  
- * @remarks To get meaningful stats this function has to be 
+ *
+ * @remarks To get meaningful stats this function has to be
  *          called twice with a bit of delay between calls. This
  *          is due to the fact that at least two samples of
  *          system usage stats are needed to calculate the load.
- *  
+ *
  * @returns None.
  */
@@ -153,9 +154,11 @@
     uint32_t u32UserDelta, u32SystemDelta;
     uint64_t u64TotalNow, u64TotalDelta;
+
+/** @todo r=bird: This is Linux specific and doesn't belong here. Move this to r3/linux/RTSystemGetCpuLoadStats-linux.cpp. */
     FILE *f = fopen("/proc/stat", "r");
 
     if (f)
     {
-        if (fscanf(f, "cpu %u %u %u %u", &u32UserNow, &u32NiceNow, &u32SystemNow, &u32IdleNow) == 4)
+        if (fscanf(f, "cpu %u %u %u %u", &u32UserNow, &u32NiceNow, &u32SystemNow, &u32IdleNow) == 4) /** @todo 'uint32_t' is not necessarily the same as 'unsigned int'. */
         {
             char *pszName;
