[docs] [issue32843] More revisions to test.support docs

[Cheryl Sabella]

New submission from Cheryl Sabella <chekat2 at gmail.com>:

Serhiy had made the following comments on the pull request for issue11015, but that PR was merged before applying his requested changes.  This issue is to address his concerns.


TESTFN_NONASCII - How different from TESTFN_UNICODE?
PGO -  value? True/False?
TEST_SUPPORT_DIR - Not used.
max_memuse - Not used.
MISSING_C_DOCSTRINGS - Remove `Return` since it's a constant.
HAVE_DOCSTRINGS - Remove `Check` since it's a constant.

Possibly group the next 3 to avoid repetition:
unlink(filename) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).
rmdir(filename) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).
rmtree(path) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).

make_legacy_pyc(source) - Add markup references to PEPs.
system_must_validate_cert(f) - This is a decorator and change text to "Skip the test on TLS certificate validation failures.".

match_test(test) and set_match_tests(patterns) - Used internally to regrtest.  Remove or ask Victor to document as the current documentation is useless.

check_impl_detail(**guards) - Document that a boolean is returned and check the docstring to include more information.

get_original_stdout - Add ().

strip_python_strerr(stderr) - Typo `strip_python_stderr` and make it clear that *stderr* is a byte string.

disable_faulthandler() - Wrong description.

disable_gc() - Add that it works only if it was enabled.

start_threads(threads, unlock=None) - Document that *threads* is a sequence of threads and document what unlock is.

calcobjsize(fmt) - Add the purpose of this - calcobjsize() returns the size of Python object (PyObject) whose structure is defined by fmt with account of Python object header.
calcvobjsize(fmt) - Same as above for PyVarObject.

requires_freebsd_version(*min_version) - Change to skip the test instead of Raise.

cpython_only(test) - Remove argument.
no_tracing(func) - Remove argument.
refcount_test(test) - Remove argument.
reap_threads(func) - Remove argument.
bigaddrspacetest(f) - Remove argument.

import_module(name, deprecated=False, *, required_on()) - Missed =

check_free_after_iterating(test, iter, cls, args=()) - This description is misleading. This function doesn't test iter. iter is either iter or reversed, cls is a base iterable class, args are arguments for its constructor. The true description is too complex, I suggest to remove this function from the documentation.

missing_compiler_executable(cmd_names=[]) - It is used only in distutils tests and should be in distutils.tests.support.

CleanImport(*module_names) - Format DeprecationWarning as a link.

DirsOnSysPath(*paths) - Format first sys.path as a link, Keeps the first one (in the above sentence) and format other mentions as ``sys.path`` or :data:`!sys.path`.

SaveSignals() - How to use it?

Matcher() - This class is used only in test_logging, and only with TestHandler. These classes should be documented together and with references to logging. I'm not sure they should be in test.support.

BasicTestRunner() - This is an internal class used for implementing run_unittest(). No need to expose it.

TestHandler(logging.handlers.BufferingHandler) - I'm not sure it should be in test.support rather of test_logging.

assert_python_ok(*args, **env_vars) - Since this is a keyword argument name, it should be formatter as *__cleanenv*.

----------
assignee: docs at python
components: Documentation
messages: 312170
nosy: csabella, docs at python, ncoghlan, serhiy.storchaka, terry.reedy
priority: normal
severity: normal
status: open
title: More revisions to test.support docs
type: enhancement
versions: Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue32843>
_______________________________________