René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"QAPage","mainEntity":{"@type":"Question","name":"Are non-reified docstrings acceptable?","text":"
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.)
\n
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.
\n
As an example of this, here's one change that could be made in test_util.py:
\n
-# Mapping of expected failures for the test_cygpath_ok test.\n _cygpath_ok_xfails = {\n     # From _norm_cygpath_pairs:\n     (R\"C:\\Users\", \"/cygdrive/c/Users\"): \"/proc/cygdrive/c/Users\",\n     (R\"C:\\d/e\", \"/cygdrive/c/d/e\"): \"/proc/cygdrive/c/d/e\",\n     (\"C:\\\\\", \"/cygdrive/c/\"): \"/proc/cygdrive/c/\",\n     (R\"\\\\server\\BAR/\", \"//server/BAR/\"): \"//server/BAR\",\n     (R\"D:/Apps\", \"/cygdrive/d/Apps\"): \"/proc/cygdrive/d/Apps\",\n     (R\"D:/Apps\\fOO\", \"/cygdrive/d/Apps/fOO\"): \"/proc/cygdrive/d/Apps/fOO\",\n     (R\"D:\\Apps/123\", \"/cygdrive/d/Apps/123\"): \"/proc/cygdrive/d/Apps/123\",\n     # From _unc_cygpath_pairs:\n     (R\"\\\\?\\a:\\com\", \"/cygdrive/a/com\"): \"/proc/cygdrive/a/com\",\n     (R\"\\\\?\\a:/com\", \"/cygdrive/a/com\"): \"/proc/cygdrive/a/com\",\n }\n+\"\"\"Mapping of expected failures for the test_cygpath_ok test.\"\"\"
\n
(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.)
","upvoteCount":1,"answerCount":1,"acceptedAnswer":{"@type":"Answer","text":"
Thanks for bringing this up!
\n
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\" :).
","upvoteCount":2,"url":"https://github.com/gitpython-developers/GitPython/discussions/1734#discussioncomment-7484116"}}}