More docstring revisions within git.objects

EliahKagan · EliahKagan · commit e166a0a7b9dc · 2024-02-28T23:45:33.000-05:00
diff --git a/git/objects/base.py b/git/objects/base.py
@@ -98,7 +98,7 @@ def new_from_sha(cls, repo: "Repo", sha1: bytes) -> Commit_ish:
             New object instance of a type appropriate to represent the given binary sha1
 
         :param sha1:
-            20 byte binary sha1
+            20 byte binary sha1.
         """
         if sha1 == cls.NULL_BIN_SHA:
             # The NULL binsha is always the root commit.
diff --git a/git/objects/commit.py b/git/objects/commit.py
@@ -298,7 +298,7 @@ def iter_items(
             The :class:`~git.repo.base.Repo`.
 
         :param rev:
-            Revision specifier, see git-rev-parse for viable options.
+            Revision specifier. See git-rev-parse for viable options.
 
         :param paths:
             An optional path or list of paths. If set only :class:`Commit`\s that
@@ -309,7 +309,7 @@ def iter_items(
 
             * ``max_count`` is the maximum number of commits to fetch.
             * ``skip`` is the number of commits to skip.
-            * ``since`` all commits since e.g. '1970-01-01'.
+            * ``since`` selects all commits since some date, e.g. ``"1970-01-01"``.
 
         :return:
             Iterator yielding :class:`Commit` items.
@@ -380,12 +380,13 @@ def stats(self) -> Stats:
     def trailers(self) -> Dict[str, str]:
         """Deprecated. Get the trailers of the message as a dictionary.
 
-        :note: This property is deprecated, please use either :attr:`trailers_list` or
-            :attr:`trailers_dict``.
+        :note:
+            This property is deprecated, please use either :attr:`trailers_list` or
+            :attr:`trailers_dict`.
 
         :return:
-            Dictionary containing whitespace stripped trailer information. Only contains
-            the latest instance of each trailer key.
+            Dictionary containing whitespace stripped trailer information.
+            Only contains the latest instance of each trailer key.
         """
         return {k: v[0] for k, v in self.trailers_dict.items()}
 
@@ -539,7 +540,7 @@ def create_from_tree(
         author_date: Union[None, str, datetime.datetime] = None,
         commit_date: Union[None, str, datetime.datetime] = None,
     ) -> "Commit":
-        """Commit the given tree, creating a commit object.
+        """Commit the given tree, creating a :class:`Commit` object.
 
         :param repo:
             :class:`~git.repo.base.Repo` object the commit should be part of.
diff --git a/git/objects/fun.py b/git/objects/fun.py
@@ -186,8 +186,8 @@ def traverse_trees_recursive(
         given tree.
 
     :param tree_shas:
-        Iterable of shas pointing to trees. All trees must be on the same level. A
-        tree-sha may be ``None`` in which case ``None``.
+        Iterable of shas pointing to trees. All trees must be on the same level.
+        A tree-sha may be ``None``, in which case ``None``.
 
     :param path_prefix:
         A prefix to be added to the returned paths on this level.
diff --git a/git/objects/tag.py b/git/objects/tag.py
@@ -3,7 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Provides an :class:`git.objects.base.Object`-based type for annotated tags.
+"""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.
diff --git a/git/objects/tree.py b/git/objects/tree.py
@@ -166,7 +166,7 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
 
     Tree as a list:
 
-    * Access a specific blob using the ``tree['filename']`` notation.
+    * Access a specific blob using the ``tree["filename"]`` notation.
     * You may likewise access by index, like ``blob = tree[0]``.
     """
 
@@ -215,8 +215,8 @@ def _set_cache_(self, attr: str) -> None:
         # END handle attribute
 
     def _iter_convert_to_object(self, iterable: Iterable[TreeCacheTup]) -> Iterator[IndexObjUnion]:
-        """Iterable yields tuples of (binsha, mode, name), which will be converted
-        to the respective object representation.
+        """Iterable yields tuples of (binsha, mode, name), which will be converted to
+        the respective object representation.
         """
         for binsha, mode, name in iterable:
             path = join_path(self.path, name)
@@ -338,8 +338,8 @@ def traverse(
     def list_traverse(self, *args: Any, **kwargs: Any) -> IterableList[IndexObjUnion]:
         """
         :return:
-            :class:`~git.util.IterableList`IterableList with the results of the
-            traversal as produced by :meth:`traverse`
+            :class:`~git.util.IterableList` with the results of the traversal as
+            produced by :meth:`traverse`
 
             Tree -> IterableList[Union[Submodule, Tree, Blob]]
         """
diff --git a/git/objects/util.py b/git/objects/util.py
@@ -474,7 +474,7 @@ def _traverse(
         ignore_self: int = 1,
         as_edge: bool = False,
     ) -> Union[Iterator[Union["Traversable", "Blob"]], Iterator[TraversedTup]]:
-        """Iterator yielding items found when traversing self.
+        """Iterator yielding items found when traversing `self`.
 
         :param predicate:
             A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should
@@ -485,9 +485,10 @@ def _traverse(
             item ``i`` at depth ``d``. Item ``i`` will not be returned.
 
         :param depth:
-            Defines at which level the iteration should not go deeper if -1, there is no
-            limit if 0, you would effectively only get self, the root of the iteration
-            i.e. if 1, you would only get the first level of predecessors/successors.
+            Defines at which level the iteration should not go deeper if -1. There is no
+            limit if 0, you would effectively only get `self`, the root of the
+            iteration. If 1, you would only get the first level of
+            predecessors/successors.
 
         :param branch_first:
             If ``True``, items will be returned branch first, otherwise depth first.
@@ -497,8 +498,8 @@ def _traverse(
             encountered several times. Loops are prevented that way.
 
         :param ignore_self:
-            If ``True``, self will be ignored and automatically pruned from the result.
-            Otherwise it will be the first item to be returned. If `as_edge` is
+            If ``True``, `self` will be ignored and automatically pruned from the
+            result. Otherwise it will be the first item to be returned. If `as_edge` is
             ``True``, the source of the first edge is ``None``.
 
         :param as_edge:
@@ -507,7 +508,7 @@ def _traverse(
             destination.
 
         :return:
-            Iterator yielding items found when traversing self::
+            Iterator yielding items found when traversing `self`::
 
                 Commit -> Iterator[Union[Commit, Tuple[Commit, Commit]] Submodule ->
                 Iterator[Submodule, Tuple[Submodule, Submodule]] Tree ->
