ui-tests: document how CaptureTextFromWindowsTerminal() works

It is a tricky (and somewhat fragile) part of the testing framework,
let's document what it does, how, and why it's done this way.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

ui-tests/ui-test-library.ahk

@@ -62,6 +62,17 @@ RunWaitOne(command) {
    return exec.StdOut.ReadAll()
 }
 
+; This function is quite the hack. It assumes that the Windows Terminal is the active window,
+; then drags the mouse diagonally across the window to select all text and then copies it.
+;
+; This is fragile! If any other window becomes active, or if the mouse is moved,
+; the function will not work as intended.
+;
+; An alternative would be to use `ControlSend`, e.g.
+; `ControlSend '+^a', 'Windows.UI.Input.InputSite.WindowClass1', 'ahk_id ' . hwnd
+; This _kinda_ works, the text is selected (all text, in fact), but the PowerShell itself
+; _also_ processes the keyboard events and therefore they leave ugly and unintended
+; `^Ac` characters in the prompt. So that alternative is not really usable.
 CaptureTextFromWindowsTerminal() {
     ControlGetPos &cx, &cy, &cw, &ch, 'Windows.UI.Composition.DesktopWindowContentBridge1', "A"
     titleBarHeight := 54