pytest: Add some comments to explain pytest's magic (python#3034)

mypy/test/data.py

@@ -437,13 +437,17 @@ def fix_cobertura_filename(line: str) -> str:
 ##
 
 
+# This function name is special to pytest.  See
+# http://doc.pytest.org/en/latest/writing_plugins.html#initialization-command-line-and-configuration-hooks
 def pytest_addoption(parser: Any) -> None:
     group = parser.getgroup('mypy')
     group.addoption('--update-data', action='store_true', default=False,
                     help='Update test data to reflect actual output'
                          ' (supported only for certain tests)')
 
 
+# This function name is special to pytest.  See
+# http://doc.pytest.org/en/latest/writing_plugins.html#collection-hooks
 def pytest_pycollect_makeitem(collector: Any, name: str, obj: Any) -> Any:
     if not isinstance(obj, type) or not issubclass(obj, DataSuite):
         return None

pytest.ini

@@ -6,7 +6,14 @@ testpaths = mypy/test
 
 python_files = test*.py
 
-# empty patterns for default python collector, to stick to our plugin's collector
+# Where do the test cases come from?  We provide our own collection
+# logic by implementing `pytest_pycollect_makeitem` in mypy.test.data;
+# the test files import that module, and pytest sees the magic name
+# and invokes it at the relevant moment.  See
+# http://doc.pytest.org/en/latest/writing_plugins.html#collection-hooks
+
+# Because we provide our own collection logic, disable the default
+# python collector by giving it empty patterns to search for.
 python_classes =
 python_functions =