Improve docstrings about tags

EliahKagan · EliahKagan · commit 61269970f2b8 · 2024-02-28T19:15:00.000-05:00
- Fix long-outdated information in the git.objects.tag docstring
  that seems to have been left over from when there was no such
  separate module. This module has only a tag-related class, not
  all classes that derive from git.object.base.Object.

- Expand the git.objects.tag docstring to clarify what the module
  provides, add a git.refs.tag module docstring explaining what
  that provides, and cross-reference them with an explanation of
  how they differ (mentioning how this relates to git concepts).

- Expand thie git.object.tag.TagObject class docstring to include
  the term "annotated" (retaining "non-lightweight" in parentheses).
diff --git a/git/objects/tag.py b/git/objects/tag.py
@@ -3,7 +3,11 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Object-based types."""
+"""Provides an :class:`git.objects.base.Object`-based type for annotated tags.
+
+This defines the :class:`TagReference` class, which represents annotated tags.
+For lightweight tags, see the :mod:`git.refs.tag` module.
+"""
 
 from . import base
 from .util import get_object_type_by_name, parse_actor_and_date
@@ -25,8 +29,8 @@
 
 
 class TagObject(base.Object):
-    """Non-lightweight tag carrying additional information about an object we are
-    pointing to."""
+    """Annotated (i.e. non-lightweight) tag carrying additional information about an
+    object we are pointing to."""
 
     type: Literal["tag"] = "tag"
 
diff --git a/git/refs/tag.py b/git/refs/tag.py
@@ -1,6 +1,13 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
+"""Provides a :class:`~git.refs.reference.Reference`-based type for lightweight tags.
+
+This defines the :class:`TagReference` class (and its alias :class:`Tag`), which
+represents lightweight tags. For annotated tags (which are git objects), see the
+:mod:`git.objects.tag` module.
+"""
+
 from .reference import Reference
 
 __all__ = ["TagReference", "Tag"]
