[STOBJECT]

-Documented the required functions and modules.
-Minor cleanup.

svn path=/branches/GSoC_2017/shellext/; revision=75690

reactos/dll/shellext/stobject/csystray.cpp

@@ -98,6 +98,26 @@ HRESULT CSysTray::ProcessIconMessage(UINT uMsg, WPARAM wParam, LPARAM lParam, LR
     return S_FALSE;
 }
 
+/*++
+* @name NotifyIcon
+*
+* Basically a Shell_NotifyIcon wrapper.
+* Based on the parameters provided, it changes the current state of the notification icon.
+*
+* @param code
+*        Determines whether to add, delete or modify the notification icon (represented by uId).
+* @param uId
+*        Represents the particular notification icon.
+* @param hIcon
+*        A handle to an icon for the notification object.
+* @param szTip
+*        A string for the tooltip of the notification.
+* @param dwstate
+*        Determines whether to show or hide the notification icon.
+*
+* @return The error code.
+*
+*--*/
 HRESULT CSysTray::NotifyIcon(INT code, UINT uId, HICON hIcon, LPCWSTR szTip, DWORD dwstate)
 {
     NOTIFYICONDATA nim = { 0 };

reactos/dll/shellext/stobject/hotplug.cpp

@@ -28,8 +28,17 @@ static WCHAR g_strMenuSel[DISPLAY_NAME_LEN];
 static BOOL g_IsRunning = FALSE;
 static BOOL g_IsRemoving = FALSE;
 
-// Enumerate the connected removable devices
+/*++
-// TODO: Require proper enumeration and filters.
+* @name EnumHotpluggedDevices
+*
+* Enumerates the connected safely removable devices.
+*
+* @param devList
+*        List of device instances, representing the currently attached devices.
+*
+* @return The error code.
+*
+*--*/
 HRESULT EnumHotpluggedDevices(CSimpleArray<DEVINST> &devList)
 {    
     devList.RemoveAll(); // Clear current devList
@@ -39,6 +48,7 @@ HRESULT EnumHotpluggedDevices(CSimpleArray<DEVINST> &devList)
     SP_DEVINFO_DATA did = { 0 };
     did.cbSize = sizeof(did);
 
+    // Enumerate all the attached devices.
     for (int idev = 0; SetupDiEnumDeviceInfo(hdev, idev, &did); idev++)
     {
         DWORD dwCapabilities = 0, dwSize = sizeof(dwCapabilities);
@@ -54,6 +64,7 @@ HRESULT EnumHotpluggedDevices(CSimpleArray<DEVINST> &devList)
         if (cr != CR_SUCCESS)
             continue;
         
+        // Filter and make list of only the appropriate safely removable devices.
         if ( (dwCapabilities & CM_DEVCAP_REMOVABLE) &&
             !(dwCapabilities & CM_DEVCAP_DOCKDEVICE) &&
             !(dwCapabilities & CM_DEVCAP_SURPRISEREMOVALOK) &&
@@ -73,7 +84,23 @@ HRESULT EnumHotpluggedDevices(CSimpleArray<DEVINST> &devList)
     return S_OK;
 }
 
-// Pops a balloon notification
+/*++
+* @name NotifyBalloon
+*
+* Pops the balloon notification of the given notification icon.
+*
+* @param pSysTray
+*        Provides interface for acquiring CSysTray information as required.
+* @param szTitle
+*        Title for the balloon notification.
+* @param szInfo
+*        Main content for the balloon notification.
+* @param uId
+*        Represents the particular notification icon.
+*
+* @return The error code.
+*
+*--*/
 HRESULT NotifyBalloon(CSysTray* pSysTray, LPCWSTR szTitle = NULL, LPCWSTR szInfo = NULL, UINT uId = ID_ICON_HOTPLUG)
 {
     NOTIFYICONDATA nim = { 0 };
@@ -175,12 +202,13 @@ static void _ShowContextMenu(CSysTray * pSysTray)
             swprintf(strInfo, L"Problem Ejecting %wS", g_strMenuSel);
             MessageBox(0, L"The device cannot be stopped right now! Try stopping it again later!", strInfo, MB_OKCANCEL | MB_ICONEXCLAMATION);
         }
-        else //TODO
+        else
         {
             //MessageBox(0, L"Device ejected successfully!! You can safely remove the device now!", L"Safely Remove Hardware", MB_OKCANCEL | MB_ICONINFORMATION);
             g_IsRemoving = TRUE;
-            g_devList.RemoveAt(id); // thing is.. even after removing id at this point, the devnode_change occurs after some seconds of sucessful removal
+            g_devList.RemoveAt(id); /* thing is.. even after removing id at this point, the devnode_change occurs after some seconds of sucessful removal
-                                    // and since pendrive is still plugged in it gets enumerated, if problem number is not filtered.
+                                       and since pendrive is still plugged in it gets enumerated, if problem number is not filtered.
+                                    */
         }
     }
     

reactos/dll/shellext/stobject/power.cpp

@@ -25,8 +25,8 @@
 
 WINE_DEFAULT_DEBUG_CHANNEL(stobject);
 
-int br_icons[5] = { IDI_BATTCAP0, IDI_BATTCAP1, IDI_BATTCAP2, IDI_BATTCAP3, IDI_BATTCAP4 };
+int br_icons[5] = { IDI_BATTCAP0, IDI_BATTCAP1, IDI_BATTCAP2, IDI_BATTCAP3, IDI_BATTCAP4 }; // battery mode icons.
-int bc_icons[5] = { IDI_BATTCHA0, IDI_BATTCHA1, IDI_BATTCHA2, IDI_BATTCHA3, IDI_BATTCHA4 };
+int bc_icons[5] = { IDI_BATTCHA0, IDI_BATTCHA1, IDI_BATTCHA2, IDI_BATTCHA3, IDI_BATTCHA4 }; // charging mode icons.
 
 typedef struct _PWRSCHEMECONTEXT
 {
@@ -40,16 +40,25 @@ static float g_batCap = 0;
 static HICON g_hIconBattery = NULL;
 static BOOL g_IsRunning = FALSE;
 
-/*** This function enumerates the available battery devices and provides the remaining capacity
+/*++
-@param      cap: if no error occurs, then this will contatin average remaining capacity
+* @name GetBatteryState
-@param dwResult: helps in making battery type checks
+*
-{
+* Enumerates the available battery devices and provides the remaining capacity.
-Returned value includes GBS_HASBATTERY if the system has a non-UPS battery, and GBS_ONBATTERY if the system is running on a battery.
+*
-dwResult & GBS_ONBATTERY means we have not yet found AC power.
+* @param cap
-dwResult & GBS_HASBATTERY means we have found a non-UPS battery.
+*        If no error occurs, then this will contain average remaining capacity.
-}
+* @param dwResult
-@return        : error checking
+*        Helps in making battery type checks.
-*/
+*       {
+*           Returned value includes GBS_HASBATTERY if the system has a non-UPS battery,
+*           and GBS_ONBATTERY if the system is running on a battery.
+*           dwResult & GBS_ONBATTERY means we have not yet found AC power.
+*           dwResult & GBS_HASBATTERY means we have found a non-UPS battery.
+*       }
+*
+* @return The error code.
+*
+*--*/
 static HRESULT GetBatteryState(float& cap, DWORD& dwResult)
 {
     cap = 0;
@@ -148,11 +157,19 @@ static HRESULT GetBatteryState(float& cap, DWORD& dwResult)
     return S_OK;
 }
 
-/*** This function quantizes the mentioned quantity to nearest level
+/*++
-@param   p: should be a quantity in percentage
+* @name Quantize
-@param lvl: quantization level, default is 10
+* 
-@return   : nearest quantized level
+* This function quantizes the mentioned quantity to nearest level.
-*/
+* 
+* @param p
+*        Should be a quantity in percentage.
+* @param lvl
+*        Quantization level (this excludes base level 0, which will always be present), default is 10.
+*
+* @return Nearest quantized level, can be directly used as array index based on context.
+*
+*--*/
 static UINT Quantize(float p, UINT lvl = 10)
 {
     int i = 0;
@@ -163,13 +180,29 @@ static UINT Quantize(float p, UINT lvl = 10)
         return i;
     else
         return i - 1;
+/* 
+ @remarks This function uses centred/symmetric logic for quantization.
+ For the case of lvl = 4, You will get following integer levels if given (p) value falls in between the range partitions:
+     0    <= p <  12.5 : returns 0; (corresponding to 0% centre)
+     12.5 <= p <  37.5 : returns 1; (corresponding to 25% centre)
+     37.5 <= p <  62.5 : returns 2; (corresponding to 50% centre)
+     62.5 <= p <  87.5 : returns 3; (corresponding to 75% centre)
+     87.5 <= p <= 100  : returns 4; (corresponding to 100% centre)
+*/
 }
 
-/*** This function returns the respective icon as per the current battery capacity.
+/*++
-     It also does the work of setting global parameters of battery capacity and tooltips.
+* @name DynamicLoadIcon
-@param hinst: instance handle
+*
-@return     : icon handle
+* Returns the respective icon as per the current battery capacity.
-*/
+* It also does the work of setting global parameters of battery capacity and tooltips.
+*
+* @param hinst
+*        A handle to a instance of the module.
+*
+* @return The handle to respective battery icon.
+*
+*--*/
 static HICON DynamicLoadIcon(HINSTANCE hinst)
 {    
     HICON hBatIcon;

reactos/dll/shellext/stobject/stobject.cpp

@@ -4,7 +4,7 @@
  * FILE:        dll/shellext/stobject/stobject.cpp
  * PURPOSE:     COM registration services for STobject.dll
  * PROGRAMMERS: Robert Naumann
- David Quintana <gigaherz@gmail.com>
+                David Quintana <gigaherz@gmail.com>
  */
 
 #include "precomp.h"