[mypyc] Improve comments and docstrings in tests (python#12223)

Tests for multi-file and separate compilation modes are a bit
special, and it seems useful to have more documentation.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Author: JukkaL

mypyc/test-data/run-multimodule.test

@@ -1,4 +1,14 @@
--- These test cases compile two modules at a time (native and other.py)
+-- These test cases compile two or more modules at a time.
+-- Any file prefixed with "other" is compiled.
+--
+-- Note that these are run in three compilation modes: regular,
+-- multi-file and separate. See the docstrings of
+-- mypyc.test.test_run.TestRunMultiFile and
+-- mypyc.test.test_run.TestRunSeparate for more information.
+--
+-- Some of these files perform multiple incremental runs. See
+-- test-data/unit/check-incremental.test for more information
+-- about how this is specified (e.g. .2 file name suffixes).
 
 [case testMultiModulePackage]
 from p.other import g

mypyc/test/test_run.py

@@ -127,7 +127,7 @@ class TestRun(MypycDataSuite):
     base_path = test_temp_dir
     optional_out = True
     multi_file = False
-    separate = False
+    separate = False  # If True, using separate (incremental) compilation
 
     def run_case(self, testcase: DataDrivenTestCase) -> None:
         # setup.py wants to be run from the root directory of the package, which we accommodate
@@ -347,7 +347,11 @@ def get_separate(self, program_text: str,
 
 
 class TestRunMultiFile(TestRun):
-    """Run the main multi-module tests in multi-file compilation mode."""
+    """Run the main multi-module tests in multi-file compilation mode.
+
+    In multi-file mode each module gets compiled into a separate C file,
+    but all modules (C files) are compiled together.
+    """
 
     multi_file = True
     test_name_suffix = '_multi'
@@ -358,7 +362,20 @@ class TestRunMultiFile(TestRun):
 
 
 class TestRunSeparate(TestRun):
-    """Run the main multi-module tests in separate compilation mode."""
+    """Run the main multi-module tests in separate compilation mode.
+
+    In this mode there are multiple compilation groups, which are compiled
+    incrementally. Each group is compiled to a separate C file, and these C
+    files are compiled separately.
+
+    Each compiled module is placed into a separate compilation group, unless
+    overridden by a special comment. Consider this example:
+
+      # separate: [(["other.py", "other_b.py"], "stuff")]
+
+    This puts other.py and other_b.py into a compilation group named "stuff".
+    Any files not mentioned in the comment will get single-file groups.
+    """
 
     separate = True
     test_name_suffix = '_separate'