More docstring revisions within git.refs

Author: EliahKagan

git/refs/head.py

@@ -36,8 +36,8 @@ def strip_quotes(string: str) -> str:
 
 
 class HEAD(SymbolicReference):
-    """Special case of a SymbolicReference representing the repository's
-    HEAD reference."""
+    """Special case of a SymbolicReference representing the repository's HEAD
+    reference."""
 
     _HEAD_NAME = "HEAD"
     _ORIG_HEAD_NAME = "ORIG_HEAD"
@@ -66,22 +66,21 @@ def reset(
         paths: Union[PathLike, Sequence[PathLike], None] = None,
         **kwargs: Any,
     ) -> "HEAD":
-        """Reset our HEAD to the given commit optionally synchronizing
-        the index and working tree. The reference we refer to will be set to commit as
-        well.
+        """Reset our HEAD to the given commit optionally synchronizing the index and
+        working tree. The reference we refer to will be set to commit as well.
 
         :param commit:
             :class:`~git.objects.commit.Commit`, :class:`~git.refs.reference.Reference`,
             or string identifying a revision we should reset HEAD to.
 
         :param index:
-            If True, the index will be set to match the given commit.
+            If ``True``, the index will be set to match the given commit.
             Otherwise it will not be touched.
 
         :param working_tree:
-            If True, the working tree will be forcefully adjusted to match the given
+            If ``True``, the working tree will be forcefully adjusted to match the given
             commit, possibly overwriting uncommitted changes without warning.
-            If `working_tree` is True, `index` must be True as well.
+            If `working_tree` is ``True``, `index` must be ``True`` as well.
 
         :param paths:
             Single path or list of paths relative to the git root directory
@@ -90,7 +89,8 @@ def reset(
         :param kwargs:
             Additional arguments passed to ``git reset``.
 
-        :return: self
+        :return:
+            self
         """
         mode: Union[str, None]
         mode = "--soft"
@@ -151,8 +151,8 @@ def delete(cls, repo: "Repo", *heads: "Union[Head, str]", force: bool = False, *
         """Delete the given heads.
 
         :param force:
-            If True, the heads will be deleted even if they are not yet merged into the
-            main development stream. Default False.
+            If ``True``, the heads will be deleted even if they are not yet merged into
+            the main development stream. Default ``False``.
         """
         flag = "-d"
         if force:
@@ -193,7 +193,7 @@ def set_tracking_branch(self, remote_reference: Union["RemoteReference", None])
     def tracking_branch(self) -> Union["RemoteReference", None]:
         """
         :return:
-            The remote reference we are tracking, or None if we are not a tracking
+            The remote reference we are tracking, or ``None`` if we are not a tracking
             branch.
         """
         from .remote import RemoteReference
@@ -219,14 +219,14 @@ def rename(self, new_path: PathLike, force: bool = False) -> "Head":
             The prefix ``refs/heads`` is implied.
 
         :param force:
-            If True, the rename will succeed even if a head with the target name
+            If ``True``, the rename will succeed even if a head with the target name
             already exists.
 
         :return:
             self
 
         :note:
-            Respects the ref log as git commands are used.
+            Respects the ref log, as git commands are used.
         """
         flag = "-m"
         if force:
@@ -244,8 +244,8 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
         The command will fail if changed working tree files would be overwritten.
 
         :param force:
-            If True, changes to the index and the working tree will be discarded.
-            If False, :class:`~git.exc.GitCommandError` will be raised in that
+            If ``True``, changes to the index and the working tree will be discarded.
+            If ``False``, :class:`~git.exc.GitCommandError` will be raised in that
             situation.
 
         :param kwargs:

git/refs/log.py

@@ -104,15 +104,15 @@ def new(
         tz_offset: int,
         message: str,
     ) -> "RefLogEntry":  # skipcq: PYL-W0621
-        """:return: New instance of a RefLogEntry"""
+        """:return: New instance of a :class:`RefLogEntry`"""
         if not isinstance(actor, Actor):
             raise ValueError("Need actor instance, got %s" % actor)
         # END check types
         return RefLogEntry((oldhexsha, newhexsha, actor, (time, tz_offset), message))
 
     @classmethod
     def from_line(cls, line: bytes) -> "RefLogEntry":
-        """:return: New RefLogEntry instance from the given revlog line.
+        """:return: New :class:`RefLogEntry` instance from the given revlog line.
 
         :param line:
             Line bytes without trailing newline
@@ -311,7 +311,7 @@ def append_entry(
         :param config_reader:
             Configuration reader of the repository - used to obtain user information.
             May also be an :class:`~git.util.Actor` instance identifying the committer
-            directly or None.
+            directly or ``None``.
 
         :param filepath:
             Full path to the log file.
@@ -326,7 +326,7 @@ def append_entry(
             Message describing the change to the reference.
 
         :param write:
-            If True, the changes will be written right away.
+            If ``True``, the changes will be written right away.
             Otherwise the change will not be written.
 
         :return:

git/refs/reference.py

@@ -65,7 +65,7 @@ def __init__(self, repo: "Repo", path: PathLike, check_path: bool = True) -> Non
             e.g. ``refs/heads/master``.
 
         :param check_path:
-            If False, you can provide any path.
+            If ``False``, you can provide any path.
             Otherwise the path must start with the default path prefix of this type.
         """
         if check_path and not str(path).startswith(self._common_path_default + "/"):
@@ -141,8 +141,9 @@ def iter_items(
         *args: Any,
         **kwargs: Any,
     ) -> Iterator[T_References]:
-        """Equivalent to SymbolicReference.iter_items, but will return non-detached
-        references as well."""
+        """Equivalent to
+        :meth:`SymbolicReference.iter_items <git.refs.symbolic.SymbolicReference.iter_items>`,
+        but will return non-detached references as well."""
         return cls._iter_items(repo, common_path)
 
     # }END interface

git/refs/remote.py

@@ -56,7 +56,7 @@ def delete(cls, repo: "Repo", *refs: "RemoteReference", **kwargs: Any) -> None:
         """Delete the given remote references.
 
         :note:
-            kwargs are given for comparability with the base class method as we
+            `kwargs` are given for comparability with the base class method as we
             should not narrow the signature.
         """
         repo.git.branch("-d", "-r", *refs)

git/refs/symbolic.py

@@ -63,7 +63,7 @@ class SymbolicReference:
     This does not point to a specific commit, but to another
     :class:`~git.refs.head.Head`, which itself specifies a commit.
 
-    A typical example for a symbolic reference is ``HEAD``.
+    A typical example for a symbolic reference is :class:`~git.refs.head.HEAD`.
     """
 
     __slots__ = ("repo", "path")
@@ -115,8 +115,8 @@ def _get_packed_refs_path(cls, repo: "Repo") -> str:
 
     @classmethod
     def _iter_packed_refs(cls, repo: "Repo") -> Iterator[Tuple[str, str]]:
-        """Return an iterator yielding pairs of sha1/path pairs (as strings)
-        for the corresponding refs.
+        """Return an iterator yielding pairs of sha1/path pairs (as strings) for the
+        corresponding refs.
 
         :note:
             The packed refs file will be kept open as long as we iterate.
@@ -226,9 +226,9 @@ def _get_ref_info_helper(
         """
         :return:
             (str(sha), str(target_ref_path)) if available, the sha the file at rela_path
-            points to, or None.
+            points to, or ``None``.
 
-            target_ref_path is the reference we point to, or None.
+            target_ref_path is the reference we point to, or ``None``.
         """
         if ref_path:
             cls._check_ref_name_valid(ref_path)
@@ -273,7 +273,7 @@ def _get_ref_info(cls, repo: "Repo", ref_path: Union[PathLike, None]) -> Union[T
         :return: (str(sha), str(target_ref_path)) if available, the sha the file at
             rela_path points to, or None.
 
-            target_ref_path is the reference we point to, or None.
+            target_ref_path is the reference we point to, or ``None``.
         """
         return cls._get_ref_info_helper(repo, ref_path)
 
@@ -313,7 +313,7 @@ def set_commit(
         :class:`~git.objects.commit.Commit`.
 
         :raise ValueError:
-            If `commit` is not a :class:`~git.objects.commit.Commit` object or doesn't
+            If `commit` is not a :class:`~git.objects.commit.Commit` object, nor does it
             point to a commit.
 
         :return:
@@ -357,7 +357,7 @@ def set_object(
             to.
 
         :param logmsg:
-            If not None, the message will be used in the reflog entry to be written.
+            If not ``None``, the message will be used in the reflog entry to be written.
             Otherwise the reflog is not altered.
 
         :note:
@@ -491,8 +491,8 @@ def set_reference(
     def is_valid(self) -> bool:
         """
         :return:
-            True if the reference is valid, hence it can be read and points to a valid
-            object or reference.
+            ``True`` if the reference is valid, hence it can be read and points to a
+            valid object or reference.
         """
         try:
             self.object
@@ -505,7 +505,7 @@ def is_valid(self) -> bool:
     def is_detached(self) -> bool:
         """
         :return:
-            True if we are a detached reference, hence we point to a specific commit
+            ``True`` if we are a detached reference, hence we point to a specific commit
             instead to another reference.
         """
         try:
@@ -565,7 +565,7 @@ def log_append(
     def log_entry(self, index: int) -> "RefLogEntry":
         """
         :return:
-            RefLogEntry at the given index
+            :class:`~git.refs.log.RefLogEntry` at the given index
 
         :param index:
             Python list compatible positive or negative index.
@@ -582,7 +582,7 @@ def to_full_path(cls, path: Union[PathLike, "SymbolicReference"]) -> PathLike:
         """
         :return:
             String with a full repository-relative path which can be used to initialize
-            a Reference instance, for instance by using
+            a :class:`~git.refs.reference.Reference` instance, for instance by using
             :meth:`Reference.from_path <git.refs.reference.Reference.from_path>`.
         """
         if isinstance(path, SymbolicReference):
@@ -666,7 +666,7 @@ def _create(
     ) -> T_References:
         """Internal method used to create a new symbolic reference.
 
-        If `resolve` is False, the reference will be taken as is, creating a proper
+        If `resolve` is ``False``, the reference will be taken as is, creating a proper
         symbolic reference. Otherwise it will be resolved to the corresponding object
         and a detached symbolic reference will be created instead.
         """
@@ -722,12 +722,12 @@ def create(
             If it is a commit-ish, the symbolic ref will be detached.
 
         :param force:
-            If True, force creation even if a symbolic reference with that name already
-            exists. Raise :class:`OSError` otherwise.
+            If ``True``, force creation even if a symbolic reference with that name
+            already exists. Raise :class:`OSError` otherwise.
 
         :param logmsg:
-            If not None, the message to append to the reflog.
-            If None, no reflog entry is written.
+            If not ``None``, the message to append to the reflog.
+            If ``None``, no reflog entry is written.
 
         :return:
             Newly created symbolic reference
@@ -751,8 +751,8 @@ def rename(self, new_path: PathLike, force: bool = False) -> "SymbolicReference"
             In case this is a symbolic ref, there is no implied prefix.
 
         :param force:
-            If True, the rename will succeed even if a head with the target name already
-            exists. It will be overwritten in that case.
+            If ``True``, the rename will succeed even if a head with the target name
+            already exists. It will be overwritten in that case.
 
         :return:
             self
@@ -847,8 +847,8 @@ def iter_items(
         :param common_path:
             Optional keyword argument to the path which is to be shared by all returned
             Ref objects.
-            Defaults to class specific portion if None, ensuring that only refs suitable
-            for the actual class are returned.
+            Defaults to class specific portion if ``None``, ensuring that only refs
+            suitable for the actual class are returned.
 
         :return:
             A list of :class:`SymbolicReference`, each guaranteed to be a symbolic ref