Revise docstrings within git.refs

Author: EliahKagan

git/refs/head.py

@@ -52,8 +52,9 @@ def __init__(self, repo: "Repo", path: PathLike = _HEAD_NAME):
 
     def orig_head(self) -> SymbolicReference:
         """
-        :return: SymbolicReference pointing at the ORIG_HEAD, which is maintained
-            to contain the previous value of HEAD.
+        :return:
+            :class:`~git.refs.symbolic.SymbolicReference` pointing at the ORIG_HEAD,
+            which is maintained to contain the previous value of HEAD.
         """
         return SymbolicReference(self.repo, self._ORIG_HEAD_NAME)
 
@@ -66,16 +67,16 @@ def reset(
         **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.
+        the index and working tree. The reference we refer to will be set to commit as
+        well.
 
         :param commit:
-            Commit object, Reference Object or string identifying a revision we
-            should reset HEAD to.
+            :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. Otherwise
-            it will not be touched.
+            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
@@ -87,7 +88,7 @@ def reset(
             that are to be reset. This allows to partially reset individual files.
 
         :param kwargs:
-            Additional arguments passed to git-reset.
+            Additional arguments passed to ``git reset``.
 
         :return: self
         """
@@ -123,8 +124,8 @@ def reset(
 
 
 class Head(Reference):
-    """A Head is a named reference to a Commit. Every Head instance contains a name
-    and a Commit object.
+    """A Head is a named reference to a :class:`~git.objects.commit.Commit`. Every Head
+    instance contains a name and a :class:`~git.objects.commit.Commit` object.
 
     Examples::
 
@@ -150,9 +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:
@@ -163,9 +163,11 @@ def set_tracking_branch(self, remote_reference: Union["RemoteReference", None])
         """Configure this branch to track the given remote reference. This will
         alter this branch's configuration accordingly.
 
-        :param remote_reference: The remote reference to track or None to untrack
-            any references.
-        :return: self
+        :param remote_reference:
+            The remote reference to track or None to untrack any references.
+
+        :return:
+            self
         """
         from .remote import RemoteReference
 
@@ -190,8 +192,10 @@ 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 branch."""
+        :return:
+            The remote reference we are tracking, or None if we are not a tracking
+            branch.
+        """
         from .remote import RemoteReference
 
         reader = self.config_reader()
@@ -211,16 +215,18 @@ def rename(self, new_path: PathLike, force: bool = False) -> "Head":
         """Rename self to a new path.
 
         :param new_path:
-            Either a simple name or a path, i.e. new_name or features/new_name.
-            The prefix refs/heads is implied.
+            Either a simple name or a path, e.g. ``new_name`` or ``features/new_name``.
+            The prefix ``refs/heads`` is implied.
 
         :param force:
             If True, the rename will succeed even if a head with the target name
             already exists.
 
-        :return: self
+        :return:
+            self
 
-        :note: Respects the ref log as git commands are used.
+        :note:
+            Respects the ref log as git commands are used.
         """
         flag = "-m"
         if force:
@@ -247,15 +253,15 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
             ``b="new_branch"`` to create a new branch at the given spot.
 
         :return:
-            The active branch after the checkout operation, usually self unless
-            a new branch has been created.
+            The active branch after the checkout operation, usually self unless a new
+            branch has been created.
             If there is no active branch, as the HEAD is now detached, the HEAD
             reference will be returned instead.
 
         :note:
-            By default it is only allowed to checkout heads - everything else
-            will leave the HEAD detached which is allowed and possible, but remains
-            a special state that some tools might not be able to handle.
+            By default it is only allowed to checkout heads - everything else will leave
+            the HEAD detached which is allowed and possible, but remains a special state
+            that some tools might not be able to handle.
         """
         kwargs["f"] = force
         if kwargs["f"] is False:
@@ -279,15 +285,17 @@ def _config_parser(self, read_only: bool) -> SectionConstraint[GitConfigParser]:
 
     def config_reader(self) -> SectionConstraint[GitConfigParser]:
         """
-        :return: A configuration parser instance constrained to only read
-            this instance's values.
+        :return:
+            A configuration parser instance constrained to only read this instance's
+            values.
         """
         return self._config_parser(read_only=True)
 
     def config_writer(self) -> SectionConstraint[GitConfigParser]:
         """
-        :return: A configuration writer instance with read-and write access
-            to options of this head.
+        :return:
+            A configuration writer instance with read-and write access to options of
+            this head.
         """
         return self._config_parser(read_only=False)
 

git/refs/log.py

@@ -44,6 +44,7 @@ class RefLogEntry(Tuple[str, str, Actor, Tuple[int, int], str]):
     """Named tuple allowing easy access to the revlog data fields."""
 
     _re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{40}$")
+
     __slots__ = ()
 
     def __repr__(self) -> str:
@@ -81,7 +82,7 @@ def actor(self) -> Actor:
 
     @property
     def time(self) -> Tuple[int, int]:
-        """time as tuple:
+        """Time as tuple:
 
         * [0] = ``int(time)``
         * [1] = ``int(timezone_offset)`` in :attr:`time.altzone` format
@@ -113,9 +114,11 @@ def new(
     def from_line(cls, line: bytes) -> "RefLogEntry":
         """:return: New RefLogEntry instance from the given revlog line.
 
-        :param line: Line bytes without trailing newline
+        :param line:
+            Line bytes without trailing newline
 
-        :raise ValueError: If `line` could not be parsed
+        :raise ValueError:
+            If `line` could not be parsed.
         """
         line_str = line.decode(defenc)
         fields = line_str.split("\t", 1)
@@ -147,9 +150,9 @@ def from_line(cls, line: bytes) -> "RefLogEntry":
 
 
 class RefLog(List[RefLogEntry], Serializable):
-    """A reflog contains RefLogEntrys, each of which defines a certain state
-    of the head in question. Custom query methods allow to retrieve log entries
-    by date or by other criteria.
+    R"""A reflog contains :class:`RefLogEntry`\s, each of which defines a certain state
+    of the head in question. Custom query methods allow to retrieve log entries by date
+    or by other criteria.
 
     Reflog entries are ordered. The first added entry is first in the list. The last
     entry, i.e. the last change of the head or reference, is last in the list.
@@ -163,8 +166,8 @@ def __new__(cls, filepath: Union[PathLike, None] = None) -> "RefLog":
 
     def __init__(self, filepath: Union[PathLike, None] = None):
         """Initialize this instance with an optional filepath, from which we will
-        initialize our data. The path is also used to write changes back using
-        the write() method."""
+        initialize our data. The path is also used to write changes back using the
+        :meth:`write` method."""
         self._path = filepath
         if filepath is not None:
             self._read_from_file()
@@ -189,31 +192,40 @@ def _read_from_file(self) -> None:
     @classmethod
     def from_file(cls, filepath: PathLike) -> "RefLog":
         """
-        :return: A new RefLog instance containing all entries from the reflog
-            at the given filepath
-        :param filepath: Path to reflog
-        :raise ValueError: If the file could not be read or was corrupted in some way
+        :return:
+            A new :class:`RefLog` instance containing all entries from the reflog at the
+            given `filepath`.
+
+        :param filepath:
+            Path to reflog.
+
+        :raise ValueError:
+            If the file could not be read or was corrupted in some way.
         """
         return cls(filepath)
 
     @classmethod
     def path(cls, ref: "SymbolicReference") -> str:
         """
-        :return: String to absolute path at which the reflog of the given ref
-            instance would be found. The path is not guaranteed to point to a valid
-            file though.
-        :param ref: SymbolicReference instance
+        :return:
+            String to absolute path at which the reflog of the given ref instance would
+            be found. The path is not guaranteed to point to a valid file though.
+
+        :param ref:
+            :class:`~git.refs.symbolic.SymbolicReference` instance
         """
         return osp.join(ref.repo.git_dir, "logs", to_native_path(ref.path))
 
     @classmethod
     def iter_entries(cls, stream: Union[str, "BytesIO", mmap]) -> Iterator[RefLogEntry]:
         """
-        :return: Iterator yielding RefLogEntry instances, one for each line read
+        :return:
+            Iterator yielding :class:`RefLogEntry` instances, one for each line read
             from the given stream.
 
-        :param stream: File-like object containing the revlog in its native format
-            or string instance pointing to a file to read.
+        :param stream:
+            File-like object containing the revlog in its native format or string
+            instance pointing to a file to read.
         """
         new_entry = RefLogEntry.from_line
         if isinstance(stream, str):
@@ -233,18 +245,23 @@ def iter_entries(cls, stream: Union[str, "BytesIO", mmap]) -> Iterator[RefLogEnt
     @classmethod
     def entry_at(cls, filepath: PathLike, index: int) -> "RefLogEntry":
         """
-        :return: RefLogEntry at the given index.
+        :return:
+            :class:`RefLogEntry` at the given index.
 
-        :param filepath: Full path to the index file from which to read the entry.
+        :param filepath:
+            Full path to the index file from which to read the entry.
 
-        :param index: Python list compatible index, i.e. it may be negative to
-            specify an entry counted from the end of the list.
+        :param index:
+            Python list compatible index, i.e. it may be negative to specify an entry
+            counted from the end of the list.
 
-        :raise IndexError: If the entry didn't exist.
+        :raise IndexError:
+            If the entry didn't exist.
 
-        .. note:: This method is faster as it only parses the entry at index, skipping
-            all other lines. Nonetheless, the whole file has to be read if
-            the index is negative.
+        :note:
+            This method is faster as it only parses the entry at index, skipping all
+            other lines. Nonetheless, the whole file has to be read if the index is
+            negative.
         """
         with open(filepath, "rb") as fp:
             if index < 0:
@@ -264,7 +281,8 @@ def entry_at(cls, filepath: PathLike, index: int) -> "RefLogEntry":
     def to_file(self, filepath: PathLike) -> None:
         """Write the contents of the reflog instance to a file at the given filepath.
 
-        :param filepath: Path to file, parent directories are assumed to exist.
+        :param filepath:
+            Path to file. Parent directories are assumed to exist.
         """
         lfd = LockedFD(filepath)
         assure_directory_exists(filepath, is_file=True)
@@ -290,19 +308,32 @@ def append_entry(
     ) -> "RefLogEntry":
         """Append a new log entry to the revlog at filepath.
 
-        :param config_reader: Configuration reader of the repository - used to obtain
-            user information. May also be an Actor instance identifying the committer
+        :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.
-        :param filepath: Full path to the log file.
-        :param oldbinsha: Binary sha of the previous commit.
-        :param newbinsha: Binary sha of the current commit.
-        :param message: Message describing the change to the reference.
-        :param write: If True, the changes will be written right away. Otherwise the
-            change will not be written.
 
-        :return: RefLogEntry objects which was appended to the log.
+        :param filepath:
+            Full path to the log file.
+
+        :param oldbinsha:
+            Binary sha of the previous commit.
+
+        :param newbinsha:
+            Binary sha of the current commit.
+
+        :param message:
+            Message describing the change to the reference.
+
+        :param write:
+            If True, the changes will be written right away.
+            Otherwise the change will not be written.
+
+        :return:
+            :class:`RefLogEntry` objects which was appended to the log.
 
-        :note: As we are append-only, concurrent access is not a problem as we do not
+        :note:
+            As we are append-only, concurrent access is not a problem as we do not
             interfere with readers.
         """
 
@@ -340,7 +371,8 @@ def append_entry(
     def write(self) -> "RefLog":
         """Write this instance's data to the file we are originating from.
 
-        :return: self
+        :return:
+            self
         """
         if self._path is None:
             raise ValueError("Instance was not initialized with a path, use to_file(...) instead")