more callback docs

Author: RalfJung

src/ci/docker/x86_64-gnu-tools/repo.sh

@@ -62,10 +62,13 @@ commit_toolstate_change() {
     MESSAGE_FILE="$1"
     shift
     for RETRY_COUNT in 1 2 3 4 5; do
-        # Call the callback; this will in the end call `change_toolstate` from
-        # `checktools.sh` if we are in the `auto` branch (pre-landing) or
-        # `src/tools/publish_toolstate.py` if we are in the `master` branch
-        # (post-landing).
+        # Call the callback.
+        # - If we are in the `auto` branch (pre-landing), this is called from `checktools.sh` and
+        #   the callback is `change_toolstate` in that file. The purpose of this is to publish the
+        #   test results (the new commit-to-toolstate mapping) in the toolstate repo.
+        # - If we are in the `master` branch (post-landing), this is called by the CI pipeline
+        #   and the callback is `src/tools/publish_toolstate.py`. The purpose is to publish
+        #   the new "current" toolstate in the toolstate repo.
         "$@"
         # `git commit` failing means nothing to commit.
         FAILURE=0

src/tools/publish_toolstate.py

@@ -1,6 +1,9 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+## This is set as callback for `src/ci/docker/x86_64-gnu-tools/repo.sh` by the CI scripts
+## when a new commit lands on `master` (i.e., after it passed all checks on `auto`).
+
 import sys
 import re
 import os