Merge pull request #1735 from EliahKagan/moddoc

Revise and restore some module docstrings

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