Are non-reified docstrings acceptable? · gitpython-developers/GitPython · Discussion #1734 (original) (raw)

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.)