Further revise other docstrings within git.objects

EliahKagan · EliahKagan · commit bc48d264df65 · 2024-02-28T18:46:22.000-05:00
diff --git a/git/objects/base.py b/git/objects/base.py
@@ -58,7 +58,7 @@ 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.
+        All keyword arguments will be set on demand if ``None``.
 
         :param repo:
             Repository this object is located in.
@@ -83,7 +83,7 @@ def new(cls, repo: "Repo", id: Union[str, "Reference"]) -> Commit_ish:
             input id may have been a `~git.refs.reference.Reference` or rev-spec.
 
         :param id:
-            :class:`~git.refs.reference.Reference`, rev-spec, or hexsha
+            :class:`~git.refs.reference.Reference`, rev-spec, or hexsha.
 
         :note:
             This cannot be a ``__new__`` method as it would always call :meth:`__init__`
@@ -119,13 +119,13 @@ def _set_cache_(self, attr: str) -> None:
             super()._set_cache_(attr)
 
     def __eq__(self, other: Any) -> bool:
-        """:return: True if the objects have the same SHA1"""
+        """:return: ``True`` if the objects have the same SHA1"""
         if not hasattr(other, "binsha"):
             return False
         return self.binsha == other.binsha
 
     def __ne__(self, other: Any) -> bool:
-        """:return: True if the objects do not have the same SHA1"""
+        """:return: ``True`` if the objects do not have the same SHA1"""
         if not hasattr(other, "binsha"):
             return True
         return self.binsha != other.binsha
@@ -199,8 +199,8 @@ def __init__(
             20 byte sha1.
 
         :param mode:
-            The stat compatible file mode as int, use the :mod:`stat` module to evaluate
-            the information.
+            The stat-compatible file mode as :class:`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
diff --git a/git/objects/blob.py b/git/objects/blob.py
@@ -27,7 +27,8 @@ class Blob(base.IndexObject):
     @property
     def mime_type(self) -> str:
         """
-        :return: String describing the mime type of this file (based on the filename)
+        :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.
diff --git a/git/objects/commit.py b/git/objects/commit.py
@@ -108,20 +108,20 @@ def __init__(
         encoding: Union[str, None] = None,
         gpgsig: Union[str, None] = None,
     ) -> None:
-        R"""Instantiate a new :class:`Commit`. All keyword arguments taking None as
+        R"""Instantiate a new :class:`Commit`. All keyword arguments taking ``None`` as
         default will be implicitly set on first query.
 
         :param binsha:
-            20 byte sha1
+            20 byte sha1.
 
         :param parents: tuple(Commit, ...)
             A tuple of commit ids or actual :class:`Commit`\s.
 
         :param tree:
             A :class:`~git.objects.tree.Tree` object.
 
-        :param author: :class:`~git.util.Actor`
-            The author Actor object
+        :param author:
+            The author :class:`~git.util.Actor` object.
 
         :param authored_date: int_seconds_since_epoch
             The authored DateTime - use :func:`time.gmtime` to convert it into a
@@ -130,8 +130,8 @@ def __init__(
         :param author_tz_offset: int_seconds_west_of_utc
             The timezone that the `authored_date` is in.
 
-        :param committer: :class:`~git.util.Actor`
-            The committer string.
+        :param committer:
+            The committer string, as an :class:`~git.util.Actor` object.
 
         :param committed_date: int_seconds_since_epoch
             The committed DateTime - use :func:`time.gmtime` to convert it into a
@@ -209,7 +209,7 @@ def _calculate_sha_(cls, repo: "Repo", commit: "Commit") -> bytes:
         return istream.binsha
 
     def replace(self, **kwargs: Any) -> "Commit":
-        """Create new commit object from existing commit object.
+        """Create new commit object from an existing commit object.
 
         Any values provided as keyword arguments will replace the corresponding
         attribute in the new object.
@@ -295,7 +295,7 @@ def iter_items(
         R"""Find all commits matching the given criteria.
 
         :param repo:
-            The Repo
+            The :class:`~git.repo.base.Repo`.
 
         :param rev:
             Revision specifier, see git-rev-parse for viable options.
@@ -378,7 +378,7 @@ def stats(self) -> Stats:
 
     @property
     def trailers(self) -> Dict[str, str]:
-        """Get the trailers of the message as a dictionary
+        """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``.
@@ -396,7 +396,7 @@ def trailers_list(self) -> List[Tuple[str, str]]:
         Git messages can contain trailer information that are similar to RFC 822 e-mail
         headers (see: https://git-scm.com/docs/git-interpret-trailers).
 
-        This functions calls ``git interpret-trailers --parse`` onto the message to
+        This function calls ``git interpret-trailers --parse`` onto the message to
         extract the trailer information, returns the raw trailer data as a list.
 
         Valid message with trailer::
@@ -444,7 +444,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
         Git messages can contain trailer information that are similar to RFC 822 e-mail
         headers (see: https://git-scm.com/docs/git-interpret-trailers).
 
-        This functions calls ``git interpret-trailers --parse`` onto the message to
+        This function calls ``git interpret-trailers --parse`` onto the message to
         extract the trailer information. The key value pairs are stripped of leading and
         trailing whitespaces before they get saved into a dictionary.
 
@@ -481,7 +481,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
     def _iter_from_process_or_stream(cls, repo: "Repo", proc_or_stream: Union[Popen, IO]) -> Iterator["Commit"]:
         """Parse out commit information into a list of :class:`Commit` objects.
 
-        We expect one-line per commit, and parse the actual commit information directly
+        We expect one line per commit, and parse the actual commit information directly
         from our lighting fast object database.
 
         :param proc:
@@ -555,11 +555,11 @@ def create_from_tree(
         :param parent_commits:
             Optional :class:`Commit` objects to use as parents for the new commit. If
             empty list, the commit will have no parents at all and become a root commit.
-            If None, the current head commit will be the parent of the new commit
+            If ``None``, the current head commit will be the parent of the new commit
             object.
 
         :param head:
-            If True, the HEAD will be advanced to the new commit automatically.
+            If ``True``, the HEAD will be advanced to the new commit automatically.
             Otherwise the HEAD will remain pointing on the previous commit. This could
             lead to undesired results when diffing files.
 
diff --git a/git/objects/fun.py b/git/objects/fun.py
@@ -128,7 +128,7 @@ def tree_entries_from_data(data: bytes) -> List[EntryTup]:
 
 
 def _find_by_name(tree_data: MutableSequence[EntryTupOrNone], name: str, is_dir: bool, start_at: int) -> EntryTupOrNone:
-    """Return data entry matching the given name and tree mode or None.
+    """Return data entry matching the given name and tree mode or ``None``.
 
     Before the item is returned, the respective data item is set None in the `tree_data`
     list to mark it done.
@@ -172,7 +172,8 @@ def traverse_trees_recursive(
     odb: "GitCmdObjectDB", tree_shas: Sequence[Union[bytes, None]], path_prefix: str
 ) -> List[Tuple[EntryTupOrNone, ...]]:
     """
-    :return: list of list with entries according to the given binary tree-shas.
+    :return:
+        List of list with entries according to the given binary tree-shas.
 
         The result is encoded in a list
         of n tuple|None per blob/commit, (n == len(tree_shas)), where:
@@ -181,12 +182,12 @@ def traverse_trees_recursive(
         * [1] == mode as int
         * [2] == path relative to working tree root
 
-        The entry tuple is None if the respective blob/commit did not exist in the given
-        tree.
+        The entry tuple is ``None`` if the respective blob/commit did not exist in the
+        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.
+        tree-sha may be ``None`` in which case ``None``.
 
     :param path_prefix:
         A prefix to be added to the returned paths on this level.
@@ -257,7 +258,8 @@ def traverse_trees_recursive(
 
 def traverse_tree_recursive(odb: "GitCmdObjectDB", tree_sha: bytes, path_prefix: str) -> List[EntryTup]:
     """
-    :return: list of entries of the tree pointed to by the binary `tree_sha`.
+    :return:
+        List of entries of the tree pointed to by the binary `tree_sha`.
 
         An entry has the following format:
 
diff --git a/git/objects/tree.py b/git/objects/tree.py
@@ -97,17 +97,17 @@ def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeMod
 
         If an item with the given name already exists, nothing will be done, but a
         :class:`ValueError` will be raised if the sha and mode of the existing item do
-        not match the one you add, unless `force` is True.
+        not match the one you add, unless `force` is ``True``.
 
         :param sha:
             The 20 or 40 byte sha of the item to add.
 
         :param mode:
-            int representing the stat compatible mode of the item.
+            :class:`int` representing the stat-compatible mode of the item.
 
         :param force:
-            If True, an item with your name and information will overwrite any existing
-            item with the same name, no matter which information it has.
+            If ``True``, an item with your name and information will overwrite any
+            existing item with the same name, no matter which information it has.
 
         :return:
             self
@@ -164,11 +164,10 @@ 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:`~git.objects.tree.Tree`\s.
 
-    Tree as a list::
+    Tree as a list:
 
-        Access a specific blob using the ``tree['filename']`` notation.
-
-        You may likewise access by index, like ``blob = tree[0]``.
+    * Access a specific blob using the ``tree['filename']`` notation.
+    * You may likewise access by index, like ``blob = tree[0]``.
     """
 
     type: Literal["tree"] = "tree"
@@ -235,7 +234,7 @@ def join(self, file: str) -> IndexObjUnion:
             or :class:`~git.objects.submodule.base.Submodule`
 
         :raise KeyError:
-            If the given file or tree does not exist in tree.
+            If the given file or tree does not exist in this tree.
         """
         msg = "Blob or Tree named %r not found"
         if "/" in file:
@@ -275,12 +274,12 @@ def __truediv__(self, file: str) -> IndexObjUnion:
 
     @property
     def trees(self) -> List["Tree"]:
-        """:return: list(Tree, ...) list of trees directly below this tree"""
+        """:return: list(Tree, ...) List of trees directly below this tree"""
         return [i for i in self if i.type == "tree"]
 
     @property
     def blobs(self) -> List[Blob]:
-        """:return: list(Blob, ...) list of blobs directly below this tree"""
+        """:return: list(Blob, ...) List of blobs directly below this tree"""
         return [i for i in self if i.type == "blob"]
 
     @property
@@ -342,7 +341,7 @@ def list_traverse(self, *args: Any, **kwargs: Any) -> IterableList[IndexObjUnion
             :class:`~git.util.IterableList`IterableList with the results of the
             traversal as produced by :meth:`traverse`
 
-            Tree -> IterableList[Union['Submodule', 'Tree', 'Blob']]
+            Tree -> IterableList[Union[Submodule, Tree, Blob]]
         """
         return super()._list_traverse(*args, **kwargs)
 
diff --git a/git/objects/util.py b/git/objects/util.py
@@ -95,9 +95,9 @@ def mode_str_to_int(modestr: Union[bytes, str]) -> int:
         used.
 
     :return:
-        String identifying a mode compatible to the mode methods ids of the stat module
-        regarding the rwx permissions for user, group and other, special flags and file
-        system flags, such as whether it is a symlink.
+        String identifying a mode compatible to the mode methods ids of the :mod:`stat`
+        module regarding the rwx permissions for user, group and other, special flags
+        and file system flags, such as whether it is a symlink.
     """
     mode = 0
     for iteration, char in enumerate(reversed(modestr[-6:])):
@@ -401,7 +401,7 @@ class Tree::       (cls, Tree) -> Tuple[Tree, ...]
     def list_traverse(self, *args: Any, **kwargs: Any) -> Any:
         """Traverse self and collect all items found.
 
-        Calling this directly only the abstract base class, including via a ``super()``
+        Calling this directly on the abstract base class, including via a ``super()``
         proxy, is deprecated. Only overridden implementations should be called.
         """
         warnings.warn(
@@ -418,12 +418,13 @@ def _list_traverse(
     ) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]:
         """Traverse self and collect all items found.
 
-        :return: :class:`~git.util.IterableList` with the results of the traversal as
+        :return:
+            :class:`~git.util.IterableList` with the results of the traversal as
             produced by :meth:`traverse`::
 
-                Commit -> IterableList["Commit"]
-                Submodule ->  IterableList["Submodule"]
-                Tree -> IterableList[Union["Submodule", "Tree", "Blob"]]
+                Commit -> IterableList[Commit]
+                Submodule ->  IterableList[Submodule]
+                Tree -> IterableList[Union[Submodule, Tree, Blob]]
         """
         # Commit and Submodule have id.__attribute__ as IterableObj.
         # Tree has id.__attribute__ inherited from IndexObject.
@@ -476,32 +477,32 @@ def _traverse(
         """Iterator yielding items found when traversing self.
 
         :param predicate:
-            A function ``f(i,d)`` that returns False if item i at depth ``d`` should not
-            be included in the result.
+            A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should
+            not be included in the result.
 
         :param prune:
-            A function ``f(i,d)`` that returns True if the search should stop at item
-            ``i`` at depth ``d``. Item ``i`` will not be returned.
+            A function ``f(i,d)`` that returns ``True`` if the search should stop at
+            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.
 
         :param branch_first:
-            If True, items will be returned branch first, otherwise depth first.
+            If ``True``, items will be returned branch first, otherwise depth first.
 
         :param visit_once:
-            If True, items will only be returned once, although they might be
+            If ``True``, items will only be returned once, although they might be
             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 True, the
-            source of the first edge is None
+            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:
-            If True, return a pair of items, first being the source, second the
+            If ``True``, return a pair of items, first being the source, second the
             destination, i.e. tuple(src, dest) with the edge spanning from source to
             destination.
 
