Revise docstrings within git.objects

But not within git.objects.submodule, which was done in 63c62ed.

Author: EliahKagan

git/objects/__init__.py

@@ -14,8 +14,8 @@
 from .tag import *  # noqa: F403
 from .tree import *  # noqa: F403
 
-# Fix import dependency - add IndexObject to the util module, so that it can be
-# imported by the submodule.base.
+# Fix import dependency - add IndexObject to the util module, so that it can be imported
+# by the submodule.base.
 smutil.IndexObject = IndexObject  # type: ignore[attr-defined]  # noqa: F405
 smutil.Object = Object  # type: ignore[attr-defined]  # noqa: F405
 del smutil

git/objects/base.py

@@ -37,7 +37,9 @@
 
 
 class Object(LazyMixin):
-    """An Object which may be Blobs, Trees, Commits and Tags."""
+    """An Object which may be :class:`~git.objects.blob.Blob`,
+    :class:`~git.objects.tree.Tree`, :class:`~git.objects.commit.Commit` or
+    `~git.objects.tag.TagObject`."""
 
     NULL_HEX_SHA = "0" * 40
     NULL_BIN_SHA = b"\0" * 20
@@ -55,11 +57,14 @@ class Object(LazyMixin):
 
     def __init__(self, repo: "Repo", binsha: bytes):
         """Initialize an object by identifying it by its binary sha.
+
         All keyword arguments will be set on demand if None.
 
-        :param repo: repository this object is located in
+        :param repo:
+            Repository this object is located in.
 
-        :param binsha: 20 byte SHA1
+        :param binsha:
+            20 byte SHA1
         """
         super().__init__()
         self.repo = repo
@@ -72,24 +77,28 @@ def __init__(self, repo: "Repo", binsha: bytes):
     @classmethod
     def new(cls, repo: "Repo", id: Union[str, "Reference"]) -> Commit_ish:
         """
-        :return: New :class:`Object`` instance of a type appropriate to the object type
-            behind `id`. The id of the newly created object will be a binsha even though
-            the input id may have been a Reference or Rev-Spec.
+        :return:
+            New :class:`Object` instance of a type appropriate to the object type behind
+            `id`. The id of the newly created object will be a binsha even though the
+            input id may have been a `~git.refs.reference.Reference` or rev-spec.
 
-        :param id: reference, rev-spec, or hexsha
+        :param id:
+            :class:`~git.refs.reference.Reference`, rev-spec, or hexsha
 
-        :note: This cannot be a ``__new__`` method as it would always call
-            :meth:`__init__` with the input id which is not necessarily a binsha.
+        :note:
+            This cannot be a ``__new__`` method as it would always call :meth:`__init__`
+            with the input id which is not necessarily a binsha.
         """
         return repo.rev_parse(str(id))
 
     @classmethod
     def new_from_sha(cls, repo: "Repo", sha1: bytes) -> Commit_ish:
         """
-        :return: new object instance of a type appropriate to represent the given
-            binary sha1
+        :return:
+            New object instance of a type appropriate to represent the given binary sha1
 
-        :param sha1: 20 byte binary sha1
+        :param sha1:
+            20 byte binary sha1
         """
         if sha1 == cls.NULL_BIN_SHA:
             # The NULL binsha is always the root commit.
@@ -126,11 +135,11 @@ def __hash__(self) -> int:
         return hash(self.binsha)
 
     def __str__(self) -> str:
-        """:return: string of our SHA1 as understood by all git commands"""
+        """:return: String of our SHA1 as understood by all git commands"""
         return self.hexsha
 
     def __repr__(self) -> str:
-        """:return: string with pythonic representation of our object"""
+        """:return: String with pythonic representation of our object"""
         return '<git.%s "%s">' % (self.__class__.__name__, self.hexsha)
 
     @property
@@ -142,26 +151,32 @@ def hexsha(self) -> str:
     @property
     def data_stream(self) -> "OStream":
         """
-        :return: File Object compatible stream to the uncompressed raw data of the object
+        :return:
+            File-object compatible stream to the uncompressed raw data of the object
 
-        :note: Returned streams must be read in order.
+        :note:
+            Returned streams must be read in order.
         """
         return self.repo.odb.stream(self.binsha)
 
     def stream_data(self, ostream: "OStream") -> "Object":
         """Write our data directly to the given output stream.
 
-        :param ostream: File object compatible stream object.
-        :return: self
+        :param ostream:
+            File-object compatible stream object.
+
+        :return:
+            self
         """
         istream = self.repo.odb.stream(self.binsha)
         stream_copy(istream, ostream)
         return self
 
 
 class IndexObject(Object):
-    """Base for all objects that can be part of the index file, namely Tree, Blob and
-    SubModule objects."""
+    """Base for all objects that can be part of the index file, namely
+    :class:`~git.objects.tree.Tree`, :class:`~git.objects.blob.Blob` and
+    :class:`~git.objects.submodule.base.Submodule` objects."""
 
     __slots__ = ("path", "mode")
 
@@ -175,16 +190,22 @@ def __init__(
         mode: Union[None, int] = None,
         path: Union[None, PathLike] = None,
     ) -> None:
-        """Initialize a newly instanced IndexObject.
+        """Initialize a newly instanced :class:`IndexObject`.
+
+        :param repo:
+            The :class:`~git.repo.base.Repo` we are located in.
+
+        :param binsha:
+            20 byte sha1.
 
-        :param repo: The :class:`~git.repo.base.Repo` we are located in.
-        :param binsha: 20 byte sha1.
         :param mode:
             The stat compatible file mode as int, use the :mod:`stat` module to evaluate
             the information.
+
         :param path:
             The path to the file in the file system, relative to the git repository
             root, like ``file.ext`` or ``folder/other.ext``.
+
         :note:
             Path may not be set if the index object has been created directly, as it
             cannot be retrieved without knowing the parent tree.
@@ -198,8 +219,8 @@ def __init__(
     def __hash__(self) -> int:
         """
         :return:
-            Hash of our path as index items are uniquely identifiable by path, not
-            by their data!
+            Hash of our path as index items are uniquely identifiable by path, not by
+            their data!
         """
         return hash(self.path)
 

git/objects/blob.py

@@ -29,7 +29,8 @@ def mime_type(self) -> str:
         """
         :return: String describing the mime type of this file (based on the filename)
 
-        :note: Defaults to 'text/plain' in case the actual file type is unknown.
+        :note:
+            Defaults to ``text/plain`` in case the actual file type is unknown.
         """
         guesses = None
         if self.path: