Revise docstrings within git.repo

Author: EliahKagan

git/repo/__init__.py

@@ -1,6 +1,6 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Initialize the Repo package."""
+"""Initialize the repo package."""
 
 from .base import Repo as Repo  # noqa: F401

git/repo/base.py

@@ -57,13 +57,13 @@ def touch(filename: str) -> str:
 
 
 def is_git_dir(d: "PathLike") -> bool:
-    """This is taken from the git setup.c:is_git_directory
-    function.
+    """This is taken from the git setup.c:is_git_directory function.
 
-    @throws WorkTreeRepositoryUnsupported if it sees a worktree directory. It's quite hacky to do that here,
-            but at least clearly indicates that we don't support it.
-            There is the unlikely danger to throw if we see directories which just look like a worktree dir,
-            but are none."""
+    :raises WorkTreeRepositoryUnsupported:
+        If it sees a worktree directory. It's quite hacky to do that here, but at least
+        clearly indicates that we don't support it. There is the unlikely danger to
+        throw if we see directories which just look like a worktree dir, but are none.
+    """
     if osp.isdir(d):
         if (osp.isdir(osp.join(d, "objects")) or "GIT_OBJECT_DIRECTORY" in os.environ) and osp.isdir(
             osp.join(d, "refs")
@@ -107,15 +107,15 @@ def find_submodule_git_dir(d: "PathLike") -> Optional["PathLike"]:
         with open(d) as fp:
             content = fp.read().rstrip()
     except IOError:
-        # it's probably not a file
+        # It's probably not a file.
         pass
     else:
         if content.startswith("gitdir: "):
             path = content[8:]
 
             if Git.is_cygwin():
-                ## Cygwin creates submodules prefixed with `/cygdrive/...` suffixes.
-                # Cygwin git understands Cygwin paths much better than Windows ones
+                # Cygwin creates submodules prefixed with `/cygdrive/...` suffixes.
+                # Cygwin git understands Cygwin paths much better than Windows ones.
                 # Also the Cygwin tests are assuming Cygwin paths.
                 path = cygpath(path)
             if not osp.isabs(path):
@@ -126,9 +126,14 @@ def find_submodule_git_dir(d: "PathLike") -> Optional["PathLike"]:
 
 
 def short_to_long(odb: "GitCmdObjectDB", hexsha: str) -> Optional[bytes]:
-    """:return: long hexadecimal sha1 from the given less-than-40 byte hexsha
-        or None if no candidate could be found.
-    :param hexsha: hexsha with less than 40 byte"""
+    """
+    :return:
+        Long hexadecimal sha1 from the given less than 40 byte hexsha or None if no
+        candidate could be found.
+
+    :param hexsha:
+        hexsha with less than 40 bytes.
+    """
     try:
         return bin_to_hex(odb.partial_to_complete_sha_hex(hexsha))
     except BadObject:
@@ -140,25 +145,29 @@ def name_to_object(
     repo: "Repo", name: str, return_ref: bool = False
 ) -> Union[SymbolicReference, "Commit", "TagObject", "Blob", "Tree"]:
     """
-    :return: object specified by the given name, hexshas ( short and long )
-        as well as references are supported
-    :param return_ref: if name specifies a reference, we will return the reference
-        instead of the object. Otherwise it will raise BadObject or BadName
+    :return:
+        Object specified by the given name - hexshas (short and long) as well as
+        references are supported.
+
+    :param return_ref:
+        If True, and name specifies a reference, we will return the reference
+        instead of the object. Otherwise it will raise `~gitdb.exc.BadObject` o
+        `~gitdb.exc.BadName`.
     """
     hexsha: Union[None, str, bytes] = None
 
-    # is it a hexsha ? Try the most common ones, which is 7 to 40
+    # Is it a hexsha? Try the most common ones, which is 7 to 40.
     if repo.re_hexsha_shortened.match(name):
         if len(name) != 40:
-            # find long sha for short sha
+            # Find long sha for short sha.
             hexsha = short_to_long(repo.odb, name)
         else:
             hexsha = name
         # END handle short shas
     # END find sha if it matches
 
-    # if we couldn't find an object for what seemed to be a short hexsha
-    # try to find it as reference anyway, it could be named 'aaa' for instance
+    # If we couldn't find an object for what seemed to be a short hexsha, try to find it
+    # as reference anyway, it could be named 'aaa' for instance.
     if hexsha is None:
         for base in (
             "%s",
@@ -179,12 +188,12 @@ def name_to_object(
         # END for each base
     # END handle hexsha
 
-    # didn't find any ref, this is an error
+    # Didn't find any ref, this is an error.
     if return_ref:
         raise BadObject("Couldn't find reference named %r" % name)
     # END handle return ref
 
-    # tried everything ? fail
+    # Tried everything ? fail.
     if hexsha is None:
         raise BadName(name)
     # END assert hexsha was found
@@ -216,17 +225,27 @@ def to_commit(obj: Object) -> Union["Commit", "TagObject"]:
 
 def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
     """
-    :return: Object at the given revision, either Commit, Tag, Tree or Blob
-    :param rev: git-rev-parse compatible revision specification as string, please see
-        http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html
-        for details
-    :raise BadObject: if the given revision could not be found
-    :raise ValueError: If rev couldn't be parsed
-    :raise IndexError: If invalid reflog index is specified"""
-
-    # colon search mode ?
+    :return:
+        `~git.objects.base.Object` at the given revision, either
+        `~git.objects.commit.Commit`, `~git.refs.tag.Tag`, `~git.objects.tree.Tree` or
+        `~git.objects.blob.Blob`.
+
+    :param rev:
+        ``git rev-parse``-compatible revision specification as string. Please see
+        http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html for details.
+
+    :raise BadObject:
+        If the given revision could not be found.
+
+    :raise ValueError:
+        If `rev` couldn't be parsed.
+
+    :raise IndexError:
+        If an invalid reflog index is specified.
+    """
+    # Are we in colon search mode?
     if rev.startswith(":/"):
-        # colon search mode
+        # Colon search mode
         raise NotImplementedError("commit by message search ( regex )")
     # END handle search
 
@@ -245,7 +264,7 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
         token = rev[start]
 
         if obj is None:
-            # token is a rev name
+            # token is a rev name.
             if start == 0:
                 ref = repo.head.ref
             else:
@@ -265,41 +284,40 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
 
         start += 1
 
-        # try to parse {type}
+        # Try to parse {type}.
         if start < lr and rev[start] == "{":
             end = rev.find("}", start)
             if end == -1:
                 raise ValueError("Missing closing brace to define type in %s" % rev)
-            output_type = rev[start + 1 : end]  # exclude brace
+            output_type = rev[start + 1 : end]  # Exclude brace.
 
-            # handle type
+            # Handle type.
             if output_type == "commit":
-                pass  # default
+                pass  # Default.
             elif output_type == "tree":
                 try:
                     obj = cast(Commit_ish, obj)
                     obj = to_commit(obj).tree
                 except (AttributeError, ValueError):
-                    pass  # error raised later
+                    pass  # Error raised later.
                 # END exception handling
             elif output_type in ("", "blob"):
                 obj = cast("TagObject", obj)
                 if obj and obj.type == "tag":
                     obj = deref_tag(obj)
                 else:
-                    # cannot do anything for non-tags
+                    # Cannot do anything for non-tags.
                     pass
                 # END handle tag
             elif token == "@":
                 # try single int
                 assert ref is not None, "Require Reference to access reflog"
                 revlog_index = None
                 try:
-                    # transform reversed index into the format of our revlog
+                    # Transform reversed index into the format of our revlog.
                     revlog_index = -(int(output_type) + 1)
                 except ValueError as e:
-                    # TODO: Try to parse the other date options, using parse_date
-                    # maybe
+                    # TODO: Try to parse the other date options, using parse_date maybe.
                     raise NotImplementedError("Support for additional @{...} modes not implemented") from e
                 # END handle revlog index
 
@@ -311,23 +329,24 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
 
                 obj = Object.new_from_sha(repo, hex_to_bin(entry.newhexsha))
 
-                # make it pass the following checks
+                # Make it pass the following checks.
                 output_type = ""
             else:
                 raise ValueError("Invalid output type: %s ( in %s )" % (output_type, rev))
             # END handle output type
 
-            # empty output types don't require any specific type, its just about dereferencing tags
+            # Empty output types don't require any specific type, its just about
+            # dereferencing tags.
             if output_type and obj and obj.type != output_type:
                 raise ValueError("Could not accommodate requested object type %r, got %s" % (output_type, obj.type))
             # END verify output type
 
-            start = end + 1  # skip brace
+            start = end + 1  # Skip brace.
             parsed_to = start
             continue
         # END parse type
 
-        # try to parse a number
+        # Try to parse a number.
         num = 0
         if token != ":":
             found_digit = False
@@ -341,15 +360,14 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
                 # END handle number
             # END number parse loop
 
-            # no explicit number given, 1 is the default
-            # It could be 0 though
+            # No explicit number given, 1 is the default. It could be 0 though.
             if not found_digit:
                 num = 1
             # END set default num
         # END number parsing only if non-blob mode
 
         parsed_to = start
-        # handle hierarchy walk
+        # Handle hierarchy walk.
         try:
             obj = cast(Commit_ish, obj)
             if token == "~":
@@ -359,7 +377,7 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
                 # END for each history item to walk
             elif token == "^":
                 obj = to_commit(obj)
-                # must be n'th parent
+                # Must be n'th parent.
                 if num:
                     obj = obj.parents[num - 1]
             elif token == ":":
@@ -378,7 +396,7 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
         # END exception handling
     # END parse loop
 
-    # still no obj ? Its probably a simple name
+    # Still no obj? It's probably a simple name.
     if obj is None:
         obj = cast(Commit_ish, name_to_object(repo, rev))
         parsed_to = lr