Revise and restore some module docstrings by EliahKagan · Pull Request #1735 · gitpython-developers/GitPython (original) (raw)

Fixes #1733

In 9ccd777, several module docstrings were converted into comments or outright deleted, apparently due to at least one of them (in git/index/fun.py) and possibly others having broken Sphinx autodoc.

As discussed later in #1733, this no longer seems to be a problem, not even in git/index/fun.py where the comment included a note indicating it had.

So this converts them back to docstrings, re-adding those that were removed in 9ccd777. This also revises them, partly to avoid making outdated claims, but mostly for style and clarity. It also revises some already-present module docstrings. Other than modules 9ccd777 affected, this does not add new docstrings to modules without them.

One of the revisions made to some module docstrings here, to improve readability, is to remove language like "Module implementing" or "Module for", which was already used only in some places. However, this language is retained in the specific cases where it is clarifying, for example by avoiding documenting a module as if it the same thing as a single class implemented in it (which would be distracting because it would read as a mistake, and which could be confusing in cases where a developer uses an import with an as clause and needs to debug it because it was intended to be an import or from statement but was accidentally written as the other of those).

I have tested this on Ubuntu and Windows, with Python 3.12, with make -C doc html and inspecting some of the generated documentation (the documentation built from git/index/fun.py). Everything seems to work fine even after this change. The change causes text fo the module docstring to be added to the rendered documentation, as expected, and does not appear to break or interfere with generation of any of anything else, including documentation generated from other docstrings in the module. No errors or warnings are shown when generating the documentation.