I'd like to suggest adding the following to the Touch Bar section of the documentation.
Buttons and Widgets both have a “Predefined Action” popup menu from which you can specify an action to perform when the button or widget is pressed. Buttons and Widgets both have the same scripting options in the Controlling Other Actions category of the menu, including Execute Shell Script, Run AppleScript, Start Automator Workflow, and Post Distributed Notification.
For Buttons, the displayed icon (and, optionally, button Name) is static.
For Widgets, the displayed icon and/or text changes dynamically according to the programming of the widget.
Widgets that display script results:
“Run AppleScript and Show Return Value” and “Run Shell Script and Show Return Value” widgets can include either or both of two actions:
An action performed when you press the widget. The action is specified in the “Predefined Action” popup menu as described above under “Buttons and Widgets”, and the same actions are available.
A script continuously repeated at a specified interval. Enter this via the “Advanced Configuration” button, then either the “AppleScript to Execute” tab for an AppleScript or the “Script Configuration” tab for a shell script. A slider for specifying the repetition interval and a checkbox for whether the script also should run when the widget transitions from hidden to visible are at the bottom of the window.
If either or both of the two actions is a script, its return value will be displayed in the widget as text unless “Only show icon, not the return value” is ticked in Advanced Configuration > Appearance & Settings.
If both actions are scripts, the two scripts will supersede each other so that the widget will display the return value of the latest script to execute.
If you want to run a “Predefined Action” shell script each time the widget is pressed but you do not want it to override the displayed return value of the script entered in Advanced Configuration, the former simply should not output anything to stdout.
If you want to run a “Predefined Action” AppleScript each time the widget is pressed but you do not want it to override the displayed return value of the script entered in Advanced Configuration, the last executed step of the AppleScript should be:
return missing value