René's URL Explorer Experiment

Title: Revise docstrings, comments, and a few messages by EliahKagan · Pull Request #1850 · gitpython-developers/GitPython · GitHub

Open Graph Title: Revise docstrings, comments, and a few messages by EliahKagan · Pull Request #1850 · gitpython-developers/GitPython

X Title: Revise docstrings, comments, and a few messages by EliahKagan · Pull Request #1850 · gitpython-developers/GitPython

Description: Fixes #1845 Fixes #1847 Fixes #1849 This pull request is a sequel to #1725. Most changes are to docstrings. Notable changes: Applies revisions to recently discussed docstrings, including improving on the wording I added in #1839 and #1844, and making the changes discussed in #1845, #1847, and #1849. Revises docstrings throughout the git package along the lines of #1725, covering areas I outright missed, or where a further improvement or kind of improvement became apparent since then (either over time or due to recent rereading), or arose since then, or where I am better able to check the effect on rendered documentation, or where I am more comfortable making the change due to an improved understanding of the code being documented (or commented). Goes beyond that in making some new kinds of formatting changes to improve consistency that I had not included there, some that I had intentionally omitted at that time due to less experience with the project, and others that I only realized the benefit of more recently. See 1cd73ba for a list of many of these (that commit only covers a handful of files, but other commits made those kinds of changes to more files). Makes bigger formatting changes for readability, when reading the docstrings in the code, than in #1725. These also improve consistency, but their value is even more for readability: Putting blank lines between all sections of all docstrings (in the git package). Giving role-labeled sections a newline after the leading :role:/:role args...:. Wrapping nearly all docstrings and most comments to 88 columns. Formatting all occurrences of a class name that is intended to refer to that class with :class:, except in rare cases where there are disadvantages of doing so (e.g., the first line of a class docstring must not link to the class itself, or some readers may infer that it is a reference to another same-named class). The addition of blank lines and line breaks in docstrings is unneeded in some projects and often not done, but seems very useful to me in GitPython, where many docstrings have long sections (rather than, for example, sections like :param foo: the predecessor of *bar* that fit on a single line). The advantages of linking class names almost everywhere are that it: makes clear that the class is what is being referred to (this is not always obvious, especially in GitPython due to subtleties of Git itself and, to a lesser extent, of GitPython's design), and makes it easy to use the reference to get to information on something one is reading about. Codes all Sphinx references to classes, methods/functions, and attributes as either: Relative to the current module, top-level function, class, or method. Absolute. One effect is that there are far more absolute Sphinx references than before. This does not cause rendered Sphinx documentation to become more longwinded, because the references are written in such a way that the rendered text still omits the qualifiers (except on hover). This is mostly achieved by writing things like :class:`~a.b.c.D`, which is short for :class:`D `, though occasionally I used the latter form: when the last two parts should be shown (:meth:`D.e `), and in base classes' bulleted lists of documented subclasses where having the displayed name first lined it up better so as also to be readable unrendered in the code. There are important tradeoffs to consider here. It is not at all obvious that this is the correct choice. When I began to do it, it was not even with the intention that this would stay that way; I planned to make them all absolute, and thus obviously correct, and then thorough a combination of experimentation and consulting documentation about Sphinx and autodoc, make them relative again where correct, sufficiently reliable, and clear on reading. However, I noticed two things as I made many references absolute: Clarity seems to be greatly improved by distinguishing things in the current module from other things that only happen to be in scope due to having been imported into it. The entire module structure and logical organization of GitPython became clear when reading the docstrings in the code. Taken together with the advantage of avoiding confusing scoping issues (example: does Sphinx autodoc resolve references that are brought in scope due to TYPE_CHECKING imports?), I think it may actually be justified to leave it this way. But it may not be justified, and this is an area that I want to call attention to for review. The rendered documentation is not more longwinded as a result of doing this, but the unrendered documentation, i.e., the docstrings as written in the code, certainly are more longwinded in many cases. This potentially worsens readability. Overall readability seems improved to me, but there are two caveats to this: I've been looking at the docstrings in this state for a while as I work on them, so what is readable to me may differ from what is readable in general. I worry I may be giving with one hand and taking away with another: it may be that these absolute references are worsening readability, and by enough to make them unjustified in their current form, but that it is hard to know that this is so, because adding consistent spacing between sections (as described above) improves readability enough that it more than counterbalances it. Adds a small number of missing docstrings, and a moderately small number of previously omitted sections in docstrings. But this was not the focus. Slightly adjusts the wording of a few messages that GitPython outputs to signify errors. This is in cd8a312 (see #1844), afd943a, and c67b2e2. These are the only behavioral changes. Besides adjusting code formatting slightly in small handful of cases, these are also the only code changes outside docstrings and comments. There are some kinds of changes that are notably omitted from this pull request. These include: As in #1725, to limit the scope, I have not undertaken to update outdated documentation in doc/source/ here, and nor applied any revisions to the project readme. Unlike #1725, I've kept the scope here a bit narrower: There are no modifications to type annotations, aspects of code style other than formatting (and very few of those), or changes of any kind in doc/source/ (including no changes to its conf.py). This conspicuously excludes the git.types module from being revised. The reason is that, while docstrings should be revised there, it looks like it will make the most sense to do that together with changes to imports, which are beyond the intended scope of this pull request. This revises docstrings and (to a lesser extent) comments both in git/ and test/, but the changes in test/ are much less substantial, since there are fewer docstrings there, and tradeoffs there are different due to no part of the docstrings in the test suite being rendered by Sphinx. (This distinction is expanded on in 5cf5b60.)

Open Graph Description: Fixes #1845 Fixes #1847 Fixes #1849 This pull request is a sequel to #1725. Most changes are to docstrings. Notable changes: Applies revisions to recently discussed docstrings, including improvin...

X Description: Fixes #1845 Fixes #1847 Fixes #1849 This pull request is a sequel to #1725. Most changes are to docstrings. Notable changes: Applies revisions to recently discussed docstrings, including improvin...

Opengraph URL: https://github.com/gitpython-developers/GitPython/pull/1850

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width