Cleanup: Use C style comments, punctuation, and capitalization.

Added missing function documentation.

4 files changed, 95 insertions, 99 deletions

diff --git a/intern/ghost/intern/GHOST_SystemWin32.cpp b/intern/ghost/intern/GHOST_SystemWin32.cpp
index aa282c73c92..697290a2d69 100644
--- a/intern/ghost/intern/GHOST_SystemWin32.cpp
+++ b/intern/ghost/intern/GHOST_SystemWin32.cpp
@@ -948,12 +948,11 @@ GHOST_EventButton *GHOST_SystemWin32::processButtonEvent(GHOST_TEventType type,
 
   /* Check for active Wintab mouse emulation in addition to a tablet in range because a proximity
    * leave event might have fired before the Windows mouse up event, thus there are still tablet
-   * events to grab. The described behavior was observed in a Wacom Bamboo CTE-450.
-   */
+   * events to grab. The described behavior was observed in a Wacom Bamboo CTE-450. */
   if (window->useTabletAPI(GHOST_kTabletWintab) &&
       (window->m_tabletInRange || window->wintabSysButPressed()) &&
       processWintabEvents(type, window, mask, window->getMousePressed())) {
-    // Wintab processing only handles in-contact events.
+    /* Wintab processing only handles in-contact events. */
     return NULL;
   }
 
@@ -972,8 +971,7 @@ GHOST_TSuccess GHOST_SystemWin32::processWintabEvents(GHOST_TEventType type,
    * button event associated to a mouse button by Wintab occurs outside of WM_*BUTTON events,
    * there's no way to tell if other simultaneously pressed non-mouse mapped buttons are associated
    * to a modifier key (shift, alt, ctrl) or a system event (scroll, etc.) and thus it is not
-   * possible to determine if a mouse click event should occur.
-   */
+   * possible to determine if a mouse click event should occur. */
   if (!mousePressed && !window->wintabSysButPressed()) {
     return GHOST_kFailure;
   }
@@ -987,10 +985,9 @@ GHOST_TSuccess GHOST_SystemWin32::processWintabEvents(GHOST_TEventType type,
 
   /* We only process events that correlate to a mouse button events, so there may exist Wintab
    * button down events that were instead mapped to e.g. scroll still in the queue. We need to
-   * skip those and find the last button down mapped to mouse buttons.
-   */
+   * skip those and find the last button down mapped to mouse buttons. */
   if (!window->wintabSysButPressed()) {
-    // Assume there may be no button down event currently in the queue.
+    /* Assume there may be no button down event currently in the queue. */
     wtiIter = wintabInfo.end();
 
     for (auto it = wintabInfo.begin(); it != wintabInfo.end(); it++) {
@@ -1013,8 +1010,7 @@ GHOST_TSuccess GHOST_SystemWin32::processWintabEvents(GHOST_TEventType type,
          *
          * If we were called during a button down event create a ghost button down event, otherwise
          * don't duplicate the prior button down as it interrupts drawing immediately after
-         * changing a window.
-         */
+         * changing a window. */
         system->pushEvent(new GHOST_EventCursor(
             info.time, GHOST_kEventCursorMove, window, info.x, info.y, info.tabletData));
         if (type == GHOST_kEventButtonDown && mask == info.button) {
@@ -1042,19 +1038,19 @@ GHOST_TSuccess GHOST_SystemWin32::processWintabEvents(GHOST_TEventType type,
     }
   }
 
-  // No Wintab button found correlating to the system button event, handle it too.
-  //
-  // Wintab button up events may be handled during WM_MOUSEMOVE, before their corresponding
-  // WM_*BUTTONUP event has fired, which results in two GHOST Button up events for a single Wintab
-  // associated button event. Alternatively this Windows button up event may have been generated
-  // from a non-stylus device such as a button on the tablet pad and needs to be handled for some
-  // workflows.
-  //
-  // The ambiguity introduced by Windows and Wintab buttons being asynchronous and having no
-  // definitive way to associate each, and that the Wintab API does not provide enough information
-  // to differentiate whether the stylus down is or is not modified by another button to a
-  // non-mouse mapping, means that we must pessimistically generate mouse up events when we are
-  // unsure of an association to prevent the mouse locking into a down state.
+  /* No Wintab button found correlating to the system button event, handle it too.
+   *
+   * Wintab button up events may be handled during WM_MOUSEMOVE, before their corresponding
+   * WM_*BUTTONUP event has fired, which results in two GHOST Button up events for a single Wintab
+   * associated button event. Alternatively this Windows button up event may have been generated
+   * from a non-stylus device such as a button on the tablet pad and needs to be handled for some
+   * workflows.
+   *
+   * The ambiguity introduced by Windows and Wintab buttons being asynchronous and having no
+   * definitive way to associate each, and that the Wintab API does not provide enough information
+   * to differentiate whether the stylus down is or is not modified by another button to a
+   * non-mouse mapping, means that we must pessimistically generate mouse up events when we are
+   * unsure of an association to prevent the mouse locking into a down state. */
   if (unhandledButton) {
     if (!window->wintabSysButPressed()) {
       GHOST_TInt32 x, y;
@@ -1079,8 +1075,8 @@ void GHOST_SystemWin32::processPointerEvents(
   std::vector<GHOST_PointerInfoWin32> pointerInfo;
   GHOST_SystemWin32 *system = (GHOST_SystemWin32 *)getSystem();
 
-  // Pointer events might fire when changing windows for a device which is set to use Wintab, even
-  // when when Wintab is left enabled but set to the bottom of Wintab overlap order.
+  /* Pointer events might fire when changing windows for a device which is set to use Wintab, even
+   * when when Wintab is left enabled but set to the bottom of Wintab overlap order. */
   if (!window->useTabletAPI(GHOST_kTabletNative)) {
     return;
   }
@@ -1105,7 +1101,7 @@ void GHOST_SystemWin32::processPointerEvents(
                                               pointerInfo[0].tabletData));
       break;
     case WM_POINTERDOWN:
-      // Move cursor to point of contact because GHOST_EventButton does not include position.
+      /* Move cursor to point of contact because GHOST_EventButton does not include position. */
       system->pushEvent(new GHOST_EventCursor(pointerInfo[0].time,
                                               GHOST_kEventCursorMove,
                                               window,
@@ -1120,8 +1116,8 @@ void GHOST_SystemWin32::processPointerEvents(
       window->updateMouseCapture(MousePressed);
       break;
     case WM_POINTERUPDATE:
-      // Coalesced pointer events are reverse chronological order, reorder chronologically.
-      // Only contiguous move events are coalesced.
+      /* Coalesced pointer events are reverse chronological order, reorder chronologically.
+       * Only contiguous move events are coalesced. */
       for (GHOST_TUns32 i = pointerInfo.size(); i-- > 0;) {
         system->pushEvent(new GHOST_EventCursor(pointerInfo[i].time,
                                                 GHOST_kEventCursorMove,
@@ -1167,13 +1163,13 @@ GHOST_EventCursor *GHOST_SystemWin32::processCursorEvent(GHOST_WindowWin32 *wind
       return NULL;
     }
     else if (window->useTabletAPI(GHOST_kTabletNative)) {
-      // Tablet input handled in WM_POINTER* events. WM_MOUSEMOVE events in response to tablet
-      // input aren't normally generated when using WM_POINTER events, but manually moving the
-      // system cursor as we do in WM_POINTER handling does.
+      /* Tablet input handled in WM_POINTER* events. WM_MOUSEMOVE events in response to tablet
+       * input aren't normally generated when using WM_POINTER events, but manually moving the
+       * system cursor as we do in WM_POINTER handling does. */
       return NULL;
     }
 
-    // If using Wintab but no button event is currently active, fall through to default handling
+    /* If using Wintab but no button event is currently active, fall through to default handling. */
   }
 
   system->getCursorPosition(x_screen, y_screen);
@@ -1823,9 +1819,9 @@ LRESULT WINAPI GHOST_SystemWin32::s_wndProc(HWND hwnd, UINT msg, WPARAM wParam,
             event = processWindowEvent(GHOST_kEventWindowSize, window);
           }
 
-          // Window might be minimized while inactive. When a window is inactive but not minimized,
-          // Wintab is left enabled (to catch the case where a pen is used to activate a window).
-          // When an inactive window is minimized, we need to disable Wintab.
+          /* Window might be minimized while inactive. When a window is inactive but not minimized,
+           * Wintab is left enabled (to catch the case where a pen is used to activate a window).
+           * When an inactive window is minimized, we need to disable Wintab. */
           if (msg == WM_SIZE && wParam == SIZE_MINIMIZED) {
             window->updateWintab(false, false);
           }
diff --git a/intern/ghost/intern/GHOST_SystemWin32.h b/intern/ghost/intern/GHOST_SystemWin32.h
index 1f9b28bb7ce..06054f27c4e 100644
--- a/intern/ghost/intern/GHOST_SystemWin32.h
+++ b/intern/ghost/intern/GHOST_SystemWin32.h
@@ -322,10 +322,11 @@ class GHOST_SystemWin32 : public GHOST_System {
 
   /**
    * Creates tablet events from Wintab events.
-   * \param type            The type of pointer event
+   * \param type            The type of pointer event.
    * \param window          The window receiving the event (the active window).
    * \param mask            The button mask of the calling event.
-   * \param mousePressed    Whether the mouse is currently pressed
+   * \param mousePressed    Whether the mouse is currently pressed.
+   * \return                True if the method handled the event.
    */
   static GHOST_TSuccess processWintabEvents(GHOST_TEventType type,
                                             GHOST_WindowWin32 *window,
@@ -334,11 +335,11 @@ class GHOST_SystemWin32 : public GHOST_System {
 
   /**
    * Creates tablet events from pointer events.
-   * \param type      The type of pointer event
-   * \param window    The window receiving the event (the active window).
-   * \param wParam    The wParam from the wndproc
-   * \param lParam    The lParam from the wndproc
-   * \param eventhandled true if the method handled the event
+   * \param type            The type of pointer event.
+   * \param window          The window receiving the event (the active window).
+   * \param wParam          The wParam from the wndproc.
+   * \param lParam          The lParam from the wndproc.
+   * \param eventhandled    True if the method handled the event.
    */
   static void processPointerEvents(
       UINT type, GHOST_WindowWin32 *window, WPARAM wParam, LPARAM lParam, bool &eventhandled);
diff --git a/intern/ghost/intern/GHOST_WindowWin32.cpp b/intern/ghost/intern/GHOST_WindowWin32.cpp
index bc6f8cf2585..d9b5a9f8b65 100644
--- a/intern/ghost/intern/GHOST_WindowWin32.cpp
+++ b/intern/ghost/intern/GHOST_WindowWin32.cpp
@@ -1007,15 +1007,15 @@ void GHOST_WindowWin32::updateWintab(bool active, bool visible)
     bool enable = useTabletAPI(GHOST_kTabletWintab) && visible;
     bool overlap = enable && active;
 
-    // Disabling context while the Window is not minimized can cause issues on receiving Wintab
-    // input while changing a window for some drivers, so only disable if either Wintab had been
-    // disabled or the window is minimized.
+    /* Disabling context while the Window is not minimized can cause issues on receiving Wintab
+     * input while changing a window for some drivers, so only disable if either Wintab had been
+     * disabled or the window is minimized. */
     m_wintab.enable(m_wintab.context, enable);
     m_wintab.overlap(m_wintab.context, overlap);
 
     if (!overlap) {
-      // WT_PROXIMITY event doesn't occur unless tablet's cursor leaves the proximity while the
-      // window is active.
+      /* WT_PROXIMITY event doesn't occur unless tablet's cursor leaves the proximity while the
+       * window is active. */
       m_tabletInRange = false;
       m_wintab.numSysButtons = 0;
       m_wintab.sysButtonsPressed = 0;
@@ -1025,55 +1025,47 @@ void GHOST_WindowWin32::updateWintab(bool active, bool visible)
 
 void GHOST_WindowWin32::initializeWintab()
 {
-  // return if wintab library handle doesn't exist or wintab is already initialized
+  /* Return if wintab library handle doesn't exist or wintab is already initialized. */
   if (!m_wintab.handle || m_wintab.context) {
     return;
   }
 
-  // Let's see if we can initialize tablet here.
-  // Check if WinTab available by getting system context info.
+  /* Check if WinTab available by getting system context info. */
   LOGCONTEXT lc = {0};
   if (m_wintab.open && m_wintab.info && m_wintab.queueSizeGet && m_wintab.queueSizeSet &&
       m_wintab.info(WTI_DEFSYSCTX, 0, &lc)) {
-    // Now init the tablet
+
     /* The pressure and orientation (tilt) */
     AXIS Pressure, Orientation[3];
-
-    // Open a Wintab context
-
-    // Open the context
     lc.lcPktData = PACKETDATA;
     lc.lcPktMode = PACKETMODE;
     lc.lcMoveMask = PACKETDATA;
     lc.lcOptions |= CXO_CSRMESSAGES | CXO_MESSAGES;
-    // Wacom maps y origin to the tablet's bottom
-    // Invert to match Windows y origin mapping to the screen top
+    /* Wacom maps y origin to the tablet's bottom. Invert to match Windows y origin mapping to the
+     * screen top. */
     lc.lcOutExtY = -lc.lcOutExtY;
 
     m_wintab.info(WTI_INTERFACE, IFC_NDEVICES, &m_wintab.numDevices);
 
-    /* get the max pressure, to divide into a float */
     BOOL pressureSupport = m_wintab.info(WTI_DEVICES, DVC_NPRESSURE, &Pressure);
     m_wintab.maxPressure = pressureSupport ? Pressure.axMax : 0;
 
-    /* get the max tilt axes, to divide into floats */
     BOOL tiltSupport = m_wintab.info(WTI_DEVICES, DVC_ORIENTATION, &Orientation);
-    /* does the tablet support azimuth ([0]) and altitude ([1]) */
+    /* Does the tablet support azimuth ([0]) and altitude ([1])? */
     if (tiltSupport && Orientation[0].axResolution && Orientation[1].axResolution) {
-      /* all this assumes the minimum is 0 */
+      /* All this assumes the minimum is 0. */
       m_wintab.maxAzimuth = Orientation[0].axMax;
       m_wintab.maxAltitude = Orientation[1].axMax;
-
     }
-    else { /* no so dont do tilt stuff */
+    else { /* No so dont do tilt stuff. */
       m_wintab.maxAzimuth = m_wintab.maxAltitude = 0;
     }
 
-    // The Wintab spec says we must open the context disabled if we are using cursor masks.
+    /* The Wintab spec says we must open the context disabled if we are using cursor masks. */
     m_wintab.context = m_wintab.open(m_hWnd, &lc, FALSE);
 
-    // Wintab provides no way to determine the maximum queue size aside from checking if attempts
-    // to change the queue size are successful.
+    /* Wintab provides no way to determine the maximum queue size aside from checking if attempts
+     * to change the queue size are successful. */
     const int maxQueue = 500;
     int queueSize = m_wintab.queueSizeGet(m_wintab.context);
 
@@ -1090,14 +1082,14 @@ void GHOST_WindowWin32::initializeWintab()
          * value."
          *
          * In our case we start with a known valid queue size and in the event of failure roll
-         * back to the last valid queue size.
-         */
+         * back to the last valid queue size. The Wintab spec dates back to 16 bit Windows, thus
+         * assumes memory recently deallocated may not be available, which is no longer a practical
+         * concern. */
         m_wintab.queueSizeSet(m_wintab.context, queueSize);
         break;
       }
     }
     m_wintab.pkts.resize(queueSize);
-
   }
 }
 
@@ -1252,7 +1244,6 @@ void GHOST_WindowWin32::processWintabInfoChangeEvent(LPARAM lParam)
     m_wintab.info(WTI_INTERFACE, IFC_NDEVICES, &m_wintab.numDevices);
     updateWintab((GHOST_WindowWin32 *)system->getWindowManager()->getActiveWindow() == this,
                  !::IsIconic(m_hWnd));
-
   }
 }
 
@@ -1365,12 +1356,12 @@ GHOST_TSuccess GHOST_WindowWin32::getWintabInfo(std::vector<GHOST_WintabInfoWin3
     outWintabInfo[i].x = pkt.pkX;
     outWintabInfo[i].y = pkt.pkY;
 
-    // Some Wintab libraries don't handle relative button input correctly, so we track button
-    // presses manually. Examples include Wacom's Bamboo modifying button events in the queue when
-    // peeked, or missing events when entering the window when the context is not on top.
+    /* Some Wintab libraries don't handle relative button input correctly, so we track button
+     * presses manually. Examples include Wacom's Bamboo modifying button events in the queue when
+     * peeked, or missing events when entering the window when the context is not on top. */
     DWORD buttonsChanged = m_wintab.sysButtonsPressed ^ pkt.pkButtons;
 
-    // Find the index for the changed button from the button map.
+    /* Find the index for the changed button from the button map. */
     WORD physicalButton = 0;
     for (DWORD diff = (unsigned)buttonsChanged >> 1; diff > 0; diff = (unsigned)diff >> 1) {
       physicalButton++;
@@ -1391,7 +1382,7 @@ GHOST_TSuccess GHOST_WindowWin32::getWintabInfo(std::vector<GHOST_WintabInfoWin3
 
     m_wintab.sysButtonsPressed = pkt.pkButtons;
 
-    // Wintab does not support performance counters, so use low frequency counter instead
+    /* Wintab does not support performance counters, so use low frequency counter instead. */
     outWintabInfo[i].time = system->tickCountToMillis(pkt.pkTime);
     outWintabInfo[i].tabletData = tabletData;
   }
@@ -1408,7 +1399,7 @@ void GHOST_WindowWin32::updatePendingWintabEvents()
 
   auto &pendingEvents = m_wintab.pendingEvents;
 
-  // Clear outdated events from queue.
+  /* Clear outdated events from queue. */
   GHOST_TUns64 currTime = system->getMilliSeconds();
   GHOST_TUns64 timeout = 300;
   while (!pendingEvents.empty()) {
@@ -1421,13 +1412,13 @@ void GHOST_WindowWin32::updatePendingWintabEvents()
     }
   }
 
-  // Get new packets.
+  /* Get new packets. */
   const int numPackets = m_wintab.packetsGet(
       m_wintab.context, m_wintab.pkts.size(), m_wintab.pkts.data());
 
   int i = 0;
-  // Don't queue outdated packets, such events can include packets that occurred before the current
-  // window lost and regained focus.
+  /* Don't queue outdated packets, such events can include packets that occurred before the current
+   * window lost and regained focus. */
   for (; i < numPackets; i++) {
     GHOST_TUns64 pktTime = system->millisSinceStart(m_wintab.pkts[i].pkTime);
     if (currTime - pktTime < timeout) {
diff --git a/intern/ghost/intern/GHOST_WindowWin32.h b/intern/ghost/intern/GHOST_WindowWin32.h
index 88b6e19c69d..aacc0070e5a 100644
--- a/intern/ghost/intern/GHOST_WindowWin32.h
+++ b/intern/ghost/intern/GHOST_WindowWin32.h
@@ -438,9 +438,9 @@ class GHOST_WindowWin32 : public GHOST_Window {
   void loadCursor(bool visible, GHOST_TStandardCursor cursorShape) const;
 
   /**
-   * Handle setup and switch between Wintab and Pointer APIs
-   * \param active    Whether the window is or will be in an active state
-   * \param visible   Whether the window is currently (or will be) visible)
+   * Handle setup and switch between Wintab and Pointer APIs.
+   * \param active    Whether the window is or will be in an active state.
+   * \param visible   Whether the window is currently (or will be) visible).
    */
   void updateWintab(bool active, bool visible);
 
@@ -452,9 +452,10 @@ class GHOST_WindowWin32 : public GHOST_Window {
 
   /**
    * Translate WM_POINTER events into GHOST_PointerInfoWin32 structs.
-   * \param outPointerInfo   Storage to return resulting GHOST_PointerInfoWin32 structs
-   * \param wParam           WPARAM of the event
-   * \param lParam           LPARAM of the event
+   * \param outPointerInfo    Storage to return resulting GHOST_PointerInfoWin32 structs.
+   * \param wParam            WPARAM of the event.
+   * \param lParam            LPARAM of the event.
+   * \return                  True if outPointerInfo was updated.
    */
   GHOST_TSuccess getPointerInfo(std::vector<GHOST_PointerInfoWin32> &outPointerInfo,
                                 WPARAM wParam,
@@ -466,24 +467,26 @@ class GHOST_WindowWin32 : public GHOST_Window {
   void processWintabDisplayChangeEvent();
 
   /**
-   * Set tablet details when a cursor enters range
+   * Set tablet details when a cursor enters range.
+   * \param inRange   Whether the Wintab device is in tracking range.
    */
   void processWintabProximityEvent(bool inRange);
 
   /**
    * Handle Wintab info changes such as change in number of connected tablets.
-   * \param lParam   LPARAM of the event
+   * \param lParam   LPARAM of the event.
    */
   void processWintabInfoChangeEvent(LPARAM lParam);
 
   /**
    * Translate Wintab packets into GHOST_WintabInfoWin32 structs.
-   * \param outWintabInfo   Storage to return resulting GHOST_WintabInfoWin32 structs
-   * \return                Success if able to read packets, even if there are none
+   * \param outWintabInfo   Storage to return resulting GHOST_WintabInfoWin32 structs.
+   * \return                Success if able to read packets, even if there are none.
    */
   GHOST_TSuccess getWintabInfo(std::vector<GHOST_WintabInfoWin32> &outWintabInfo);
 
   /**
+   * Updates stored pending Wintab events.
    */
   void updatePendingWintabEvents();
 
@@ -500,25 +503,25 @@ class GHOST_WindowWin32 : public GHOST_Window {
   GHOST_TUns16 getDPIHint() override;
 
   /**
-   * Get whether there are currently any mouse buttons pressed
-   * \return    True if there are any currently pressed mouse buttons
+   * Get whether there are currently any mouse buttons pressed.
+   * \return    True if there are any currently pressed mouse buttons.
    */
   bool getMousePressed() const;
 
   /**
-   * Get if there are currently pressed Wintab buttons associated to a Windows mouse button press
+   * Get if there are currently pressed Wintab buttons associated to a Windows mouse button press.
    * \return    True if there are currently any pressed Wintab buttons associated to a Windows
-   *            mouse button press
+   *            mouse button press.
    */
   bool wintabSysButPressed() const;
 
   /**
-   * Register a Wintab button has been associated to a Windows mouse button press
-   * \param event   Whether the button was pressed or released
+   * Register a Wintab button has been associated to a Windows mouse button press.
+   * \param event   Whether the button was pressed or released.
    */
   void updateWintabSysBut(GHOST_MouseCaptureEventWin32 event);
 
-  /** Whether a tablet stylus is being tracked */
+  /** Whether a tablet stylus is being tracked. */
   bool m_tabletInRange;
 
   /** if the window currently resizing */
@@ -628,18 +631,23 @@ class GHOST_WindowWin32 : public GHOST_Window {
     DWORD sysButtonsPressed = 0;
     LONG maxPressure = 0;
     LONG maxAzimuth = 0, maxAltitude = 0;
-    /* Queue size doesn't change once set, so reuse the same buffer */
+    /** Reusable buffer to read in Wintab Packets. */
     std::vector<PACKET> pkts;
+    /** Queue of packets to process. */
     std::queue<PACKET> pendingEvents;
   } m_wintab;
 
   /**
-   * Wintab setup
+   * Wintab setup.
    */
   void initializeWintab();
 
   /**
-   * Convert Wintab system mapped (mouse) buttons into Ghost button mask
+   * Convert Wintab system mapped (mouse) buttons into Ghost button mask.
+   * \param cursor            The Wintab cursor associated to the button.
+   * \param physicalButton    The physical button ID to inspect.
+   * \param buttonMask        Return pointer for button found.
+   * \return                  Whether an associated button was found.
    */
   GHOST_TSuccess wintabMouseToGhost(UINT cursor,
                                     WORD physicalButton,