Further revise other docstrings within git.objects

Author: EliahKagan

Diff for: 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 for: 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 for: 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 for: 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 for: 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 for: 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.