Revise docstrings and comments for clarity and formatting

In the git module (including the modules it contains).

This also makes one small change in doc/ to synchronize with a
change made in a docstring.

Author: EliahKagan

Diff for: git/__init__.py

@@ -3,8 +3,10 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: https://opensource.org/license/bsd-3-clause/
+
 # flake8: noqa
 # @PydevCodeAnalysisIgnore
+
 from git.exc import *  # @NoMove @IgnorePep8
 from typing import List, Optional, Sequence, Tuple, Union, TYPE_CHECKING
 from git.types import PathLike

Diff for: git/cmd.py

@@ -1,10 +1,12 @@
 # -*- coding: utf-8 -*-
-# config.py
+# compat.py
 # Copyright (C) 2008, 2009 Michael Trier ([email protected]) and contributors
 #
 # This module is part of GitPython and is released under
 # the BSD License: https://opensource.org/license/bsd-3-clause/
-"""utilities to help provide compatibility with python 3"""
+
+"""Utilities to help provide compatibility with Python 3."""
+
 # flake8: noqa
 
 import locale
@@ -50,7 +52,7 @@ def safe_decode(s: AnyStr) -> str:
 
 
 def safe_decode(s: Union[AnyStr, None]) -> Optional[str]:
-    """Safely decodes a binary string to unicode"""
+    """Safely decode a binary string to Unicode."""
     if isinstance(s, str):
         return s
     elif isinstance(s, bytes):
@@ -72,7 +74,7 @@ def safe_encode(s: AnyStr) -> bytes:
 
 
 def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]:
-    """Safely encodes a binary string to unicode"""
+    """Safely encode a binary string to Unicode."""
     if isinstance(s, str):
         return s.encode(defenc)
     elif isinstance(s, bytes):
@@ -94,7 +96,7 @@ def win_encode(s: AnyStr) -> bytes:
 
 
 def win_encode(s: Optional[AnyStr]) -> Optional[bytes]:
-    """Encode unicodes for process arguments on Windows."""
+    """Encode Unicode strings for process arguments on Windows."""
     if isinstance(s, str):
         return s.encode(locale.getpreferredencoding(False))
     elif isinstance(s, bytes):

Diff for: git/compat.py

@@ -1,4 +1,5 @@
-"""Module with our own gitdb implementation - it uses the git command"""
+"""Module with our own gitdb implementation - it uses the git command."""
+
 from git.util import bin_to_hex, hex_to_bin
 from gitdb.base import OInfo, OStream
 from gitdb.db import GitDB
@@ -22,17 +23,17 @@
 
 
 class GitCmdObjectDB(LooseObjectDB):
-
     """A database representing the default git object store, which includes loose
-    objects, pack files and an alternates file
+    objects, pack files and an alternates file.
 
     It will create objects only in the loose object database.
-    :note: for now, we use the git command to do all the lookup, just until he
-        have packs and the other implementations
+
+    :note: For now, we use the git command to do all the lookup, just until we
+        have packs and the other implementations.
     """
 
     def __init__(self, root_path: PathLike, git: "Git") -> None:
-        """Initialize this instance with the root and a git command"""
+        """Initialize this instance with the root and a git command."""
         super(GitCmdObjectDB, self).__init__(root_path)
         self._git = git
 
@@ -48,11 +49,15 @@ def stream(self, binsha: bytes) -> OStream:
     # { Interface
 
     def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
-        """:return: Full binary 20 byte sha from the given partial hexsha
+        """
+        :return: Full binary 20 byte sha from the given partial hexsha
+
         :raise AmbiguousObjectName:
         :raise BadObject:
-        :note: currently we only raise BadObject as git does not communicate
-            AmbiguousObjects separately"""
+
+        :note: Currently we only raise :class:`BadObject` as git does not communicate
+            AmbiguousObjects separately.
+        """
         try:
             hexsha, _typename, _size = self._git.get_object_header(partial_hexsha)
             return hex_to_bin(hexsha)