[ssawant] 75690: [STOBJECT] -Documented the required functions and modules. -Minor cleanup.

Author: ssawant
Date: Sun Aug 27 11:45:46 2017
New Revision: 75690

URL: http://svn.reactos.org/svn/reactos?rev=75690&view=rev
Log:
[STOBJECT]
-Documented the required functions and modules.
-Minor cleanup.

Modified:
    branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/csystray.cpp
    branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/hotplug.cpp
    branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/power.cpp
    branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/stobject.cpp

Modified: branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/csystray.cpp
URL:
http://svn.reactos.org/svn/reactos/branches/GSoC_2017/shellext/reactos/dll/…
==============================================================================
--- branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/csystray.cpp	[iso-8859-1]
(original)
+++ branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/csystray.cpp	[iso-8859-1]
Sun Aug 27 11:45:46 2017
@@ -98,6 +98,26 @@
     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 };

Modified: branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/hotplug.cpp
URL:
http://svn.reactos.org/svn/reactos/branches/GSoC_2017/shellext/reactos/dll/…
==============================================================================
--- branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/hotplug.cpp	[iso-8859-1]
(original)
+++ branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/hotplug.cpp	[iso-8859-1] Sun
Aug 27 11:45:46 2017
@@ -28,8 +28,17 @@
 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 @@
     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 @@
         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 @@
     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 @@
             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
-                                    // and since pendrive is still plugged in it gets
enumerated, if problem number is not filtered.
+            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.
+                                    */
         }
     }
     

Modified: branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/power.cpp
URL:
http://svn.reactos.org/svn/reactos/branches/GSoC_2017/shellext/reactos/dll/…
==============================================================================
--- branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/power.cpp	[iso-8859-1]
(original)
+++ branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/power.cpp	[iso-8859-1] Sun
Aug 27 11:45:46 2017
@@ -25,8 +25,8 @@
 
 WINE_DEFAULT_DEBUG_CHANNEL(stobject);
 
-int br_icons[5] = { IDI_BATTCAP0, IDI_BATTCAP1, IDI_BATTCAP2, IDI_BATTCAP3, IDI_BATTCAP4
};
-int bc_icons[5] = { IDI_BATTCHA0, IDI_BATTCHA1, IDI_BATTCHA2, IDI_BATTCHA3, IDI_BATTCHA4
};
+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
}; // charging mode icons.
 
 typedef struct _PWRSCHEMECONTEXT
 {
@@ -40,16 +40,25 @@
 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
-@param dwResult: 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        : error checking
-*/
+/*++
+* @name GetBatteryState
+*
+* Enumerates the available battery devices and provides the remaining capacity.
+*
+* @param cap
+*        If no error occurs, then this will contain average remaining capacity.
+* @param dwResult
+*        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 @@
     return S_OK;
 }
 
-/*** This function quantizes the mentioned quantity to nearest level
-@param   p: should be a quantity in percentage
-@param lvl: quantization level, default is 10
-@return   : nearest quantized level
-*/
+/*++
+* @name Quantize
+* 
+* 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 @@
         return i;
     else
         return i - 1;
-}
-
-/*** 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.
-@param hinst: instance handle
-@return     : icon handle
+/* 
+ @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)
 */
+}
+
+/*++
+* @name DynamicLoadIcon
+*
+* 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;

Modified: branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/stobject.cpp
URL:
http://svn.reactos.org/svn/reactos/branches/GSoC_2017/shellext/reactos/dll/…
==============================================================================
--- branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/stobject.cpp	[iso-8859-1]
(original)
+++ branches/GSoC_2017/shellext/reactos/dll/shellext/stobject/stobject.cpp	[iso-8859-1]
Sun Aug 27 11:45:46 2017
@@ -4,7 +4,7 @@
  * FILE:        dll/shellext/stobject/stobject.cpp
  * PURPOSE:     COM registration services for STobject.dll
  * PROGRAMMERS: Robert Naumann
- David Quintana &lt;gigaherz(a)gmail.com&gt;
+                David Quintana &lt;gigaherz(a)gmail.com&gt;
  */
 
 #include "precomp.h"