Unlike modules, classes, and functions/methods, variables/constants do not technically support docstrings. However, it is fairly common to write what is conceptually a docstring immediately after an assignment statement, as an expression statement consisting of a triple-quoted string, with no blank line in between. This is recognized by some editors, including VS Code, as a docstring, and helpfully displayed when one hovers over or otherwise examines information on the variable/constant it documents. Of course, callinghelp on the variable/constant does not reveal it; while true docstrings become__doc__ attributes, this informal kind of docstring cannot and does not affect an object's__doc__ attribute at runtime. (It is reflected in the AST, because it is a statement, but it is non-reified in the sense that, unlike true docstrings, it has no place in the data model.)

I think it would be useful to convert some comments atop variable/constant assignment statements to this kind of "docstring", and perhaps to add them for some variables/constants that currently are not directly documented. But I wanted to check, since it may be that for this project only true docstrings are preferred.

As an example of this, here's one change that could be madeintest_util.py:

-# Mapping of expected failures for the test_cygpath_ok test. _cygpath_ok_xfails = {     # From _norm_cygpath_pairs:     (R"C:\Users", "/cygdrive/c/Users"): "/proc/cygdrive/c/Users",     (R"C:\d/e", "/cygdrive/c/d/e"): "/proc/cygdrive/c/d/e",     ("C:\\", "/cygdrive/c/"): "/proc/cygdrive/c/",     (R"\\server\BAR/", "//server/BAR/"): "//server/BAR",     (R"D:/Apps", "/cygdrive/d/Apps"): "/proc/cygdrive/d/Apps",     (R"D:/Apps\fOO", "/cygdrive/d/Apps/fOO"): "/proc/cygdrive/d/Apps/fOO",     (R"D:\Apps/123", "/cygdrive/d/Apps/123"): "/proc/cygdrive/d/Apps/123",     # From _unc_cygpath_pairs:     (R"\\?\a:\com", "/cygdrive/a/com"): "/proc/cygdrive/a/com",     (R"\\?\a:/com", "/cygdrive/a/com"): "/proc/cygdrive/a/com", }+"""Mapping of expected failures for the test_cygpath_ok test."""

(Ordinarily I might just open a PR, which could be merged or not. But exactly where I'd add these depends on decisions related to other PRs: at least#1732, and possibly also a forthcoming PR that builds on#1729. So I figured I'd post this question instead.)