Expand docs of classes representing Git objects

EliahKagan · EliahKagan · commit f3b9a695a066 · 2024-03-04T09:50:50.000-05:00
This expands the docstrings of the Object base class, as well as
the four leaf subclasses that represent git objects (Blob, Commit,
TagObject, and Tree) to clarify those classes' relationship to git
objects in general and specific types of git objects, to each
other, and where applicable to types defined in git.types.

This includes links to specific sections of the gitglossary(7)
manpage (as hosted online), where directly applicable.
diff --git a/git/objects/base.py b/git/objects/base.py
@@ -37,9 +37,33 @@
 
 
 class Object(LazyMixin):
-    """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`."""
+    """Base class for classes representing kinds of git objects.
+
+    The following leaf classes represent specific kinds of git objects:
+
+    * :class:`Blob <git.objects.blob.Blob>`
+    * :class:`Tree <git.objects.tree.Tree>`
+    * :class:`Commit <git.objects.commit.Commit>`
+    * :class:`TagObject <git.objects.tag.TagObject>`
+
+    See gitglossary(7) on:
+
+    * "object": https://git-scm.com/docs/gitglossary#def_object
+    * "object type": https://git-scm.com/docs/gitglossary#def_object_type
+    * "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    * "tree object": https://git-scm.com/docs/gitglossary#def_tree_object
+    * "commit object": https://git-scm.com/docs/gitglossary#def_commit_object
+    * "tag object": https://git-scm.com/docs/gitglossary#def_tag_object
+
+    :note:
+        See the :class:`git.types.Commit_ish` union type.
+
+    :note:
+        :class:`~git.objects.submodule.base.Submodule` is defined under the hierarchy
+        rooted at this :class:`Object` class, even though submodules are not really a
+        kind of git object.
+
+    """
 
     NULL_HEX_SHA = "0" * 40
     NULL_BIN_SHA = b"\0" * 20
@@ -54,6 +78,20 @@ class Object(LazyMixin):
     __slots__ = ("repo", "binsha", "size")
 
     type: Union[Lit_commit_ish, None] = None
+    """String identifying (a concrete :class:`Object` subtype for) a kind of git object.
+
+    The subtypes that this may name correspond to the kinds of git objects that exist,
+    i.e., the objects that may be present in a git repository.
+
+    :note:
+        Most subclasses represent specific types of git objects and override this class
+        attribute accordingly. This attribute is ``None`` in the :class:`Object` base
+        class, as well as the :class:`IndexObject` intermediate subclass, but never
+        ``None`` in concrete leaf subclasses representing specific kinds of git objects.
+
+    :note:
+        See also :class:`~git.types.Commit_ish`.
+    """
 
     def __init__(self, repo: "Repo", binsha: bytes):
         """Initialize an object by identifying it by its binary sha.
@@ -174,9 +212,12 @@ def stream_data(self, ostream: "OStream") -> "Object":
 
 
 class IndexObject(Object):
-    """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."""
+    """Base for all objects that can be part of the index file.
+
+    The classes representing kinds of git objects that can be part of the index file are
+    :class:`~git.objects.tree.Tree and :class:`~git.objects.blob.Blob`. In addition,
+    :class:`~git.objects.submodule.base.Submodule` is also a subclass.
+    """
 
     __slots__ = ("path", "mode")
 
diff --git a/git/objects/blob.py b/git/objects/blob.py
@@ -12,7 +12,10 @@
 
 
 class Blob(base.IndexObject):
-    """A Blob encapsulates a git blob object."""
+    """A Blob encapsulates a git blob object.
+
+    See gitglossary(7) on "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    """
 
     DEFAULT_MIME_TYPE = "text/plain"
     type: Literal["blob"] = "blob"
diff --git a/git/objects/commit.py b/git/objects/commit.py
@@ -60,8 +60,12 @@
 class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
     """Wraps a git commit object.
 
-    This class will act lazily on some of its attributes and will query the value on
-    demand only if it involves calling the git binary.
+    See gitglossary(7) on "commit object":
+    https://git-scm.com/docs/gitglossary#def_commit_object
+
+    :note:
+        This class will act lazily on some of its attributes and will query the value on
+        demand only if it involves calling the git binary.
     """
 
     # ENVIRONMENT VARIABLES
diff --git a/git/objects/tag.py b/git/objects/tag.py
@@ -30,7 +30,11 @@
 
 class TagObject(base.Object):
     """Annotated (i.e. non-lightweight) tag carrying additional information about an
-    object we are pointing to."""
+    object we are pointing to.
+
+    See gitglossary(7) on "tag object":
+    https://git-scm.com/docs/gitglossary#def_tag_object
+    """
 
     type: Literal["tag"] = "tag"
 
diff --git a/git/objects/tree.py b/git/objects/tree.py
@@ -164,6 +164,9 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
     R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
     other :class:`Tree`\s.
 
+    See gitglossary(7) on "tree object":
+    https://git-scm.com/docs/gitglossary#def_tree_object
+
     Subscripting is supported, as with a list or dict:
 
     * Access a specific blob using the ``tree["filename"]`` notation.
