Are non-reified docstrings acceptable?

[EliahKagan]

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, calling help 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 made in test_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.)

[Byron]

Thanks for bringing this up!

I think GitPython should try to provide a decent in-editor experience, and this seems to be improved by turning these comments on constants into non-reified docstrings. This would also be a guiding principle - there are no rules except for "don't break anyone" and "don't make it worse more than you make it better" :).