Revise and restore some module docstrings

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

git/config.py

@@ -3,8 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module containing module parser implementation able to properly read and write
-configuration files."""
+"""Parser for reading and writing configuration files."""
 
 import abc
 import configparser as cp

git/exc.py

@@ -3,7 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module containing all exceptions thrown throughout the git package."""
+"""Exceptions thrown throughout the git package."""
 
 __all__ = [
     # Defined in gitdb.exc:

git/index/base.py

@@ -3,6 +3,9 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
+"""Module containing IndexFile, an Index implementation facilitating all kinds of index
+manipulations such as querying and merging."""
+
 from contextlib import ExitStack
 import datetime
 import glob

git/index/fun.py

@@ -1,8 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-# Standalone functions to accompany the index implementation and make it more versatile.
-# NOTE: Autodoc hates it if this is a docstring.
+"""Standalone functions to accompany the index implementation and make it more versatile."""
 
 from io import BytesIO
 import os

git/index/typ.py

@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module with additional types used by the index."""
+"""Additional types used by the index."""
 
 from binascii import b2a_hex
 from pathlib import Path

git/index/util.py

@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module containing index utilities."""
+"""Index utilities."""
 
 from functools import wraps
 import os

git/objects/fun.py

@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module with functions which are supposed to be as fast as possible."""
+"""Functions that are supposed to be as fast as possible."""
 
 from stat import S_ISDIR
 

git/objects/tag.py

@@ -3,7 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module containing all Object-based types."""
+"""Object-based types."""
 
 from . import base
 from .util import get_object_type_by_name, parse_actor_and_date

git/objects/util.py

@@ -3,7 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module for general utility functions."""
+"""General utility functions."""
 
 # flake8: noqa F401
 

git/refs/head.py

@@ -1,6 +1,11 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
+"""Some ref-based objects.
+
+Note the distinction between the :class:`HEAD` and :class:`Head` classes.
+"""
+
 from git.config import GitConfigParser, SectionConstraint
 from git.util import join_path
 from git.exc import GitCommandError

git/refs/remote.py

@@ -1,6 +1,8 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
+"""Module implementing a remote object allowing easy access to git remotes."""
+
 import os
 
 from git.util import join_path

git/repo/fun.py

@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Module with general repository-related functions."""
+"""General repository-related functions."""
 
 from __future__ import annotations
 

test/test_blob_filter.py

@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Test the blob filter."""
+"""Tests for the blob filter."""
 
 from pathlib import Path
 from typing import Sequence, Tuple

test/test_exc.py

@@ -3,7 +3,6 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-
 import re
 
 import ddt

test/test_repo.py

@@ -2,6 +2,7 @@
 #
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
 import glob
 import io
 from io import BytesIO