Clarify CallableProgress vs. CallableRemoteProgress

This corrects an overstatement in the git.types.CallableProgress
docstring, which was introduced recently in 9e47083, and in which
I had erroneously claimed that it was the most general type of
object passed as a progress reporter for cloning.

There are some non-None non-callable types that can also be
passed and that are not encompassed by git.types.CallableProgress,
somewhat confusingly including CallableRemoteProgress (which like
RemoteProgress is not callable; rather, it wraps a callable and
forwards progress information to it).

In addition, None can be passed, and while
git.types.CallableProgress does encompass it, it is not callable.
(This is minor by comparison and I just added a brief note for it.)

This also further expands the git.types.CallableProgress docstring,
as well as the git.util.CallableRemoteProgress docstring, to
clarify the distinction between them, as well as what "Callable"
really signifies for CallableRemoteProgress (that it wraps and
forwards to a callable, rather than itself being callable).

Author: EliahKagan

Diff for: git/types.py

@@ -115,11 +115,25 @@
 # Progress parameter type alias -----------------------------------------
 
 CallableProgress = Optional[Callable[[int, Union[str, float], Union[str, float, None], str], None]]
-"""General type of a progress reporter for cloning.
+"""General type of a function or other callable used as a progress reporter for cloning.
 
 This is the type of a function or other callable that reports the progress of a clone,
 when passed as a ``progress`` argument to :meth:`Repo.clone <git.repo.base.Repo.clone>`
 or :meth:`Repo.clone_from <git.repo.base.Repo.clone_from>`.
+
+:note:
+    Those :meth:`~git.repo.base.Repo.clone` and :meth:`~git.repo.base.Repo.clone_from`
+    methods also accept :meth:`~git.util.RemoteProgress` instances, including instances
+    of its :meth:`~git.util.CallableRemoteProgress` subclass.
+
+:note:
+    Unlike objects that match this type, :meth:`~git.util.RemoteProgress` instances are
+    not directly callable, not even when they are instances of
+    :meth:`~git.util.CallableRemoteProgress`, which wraps a callable and forwards
+    information to it but is not itself callable.
+
+:note:
+    This type also allows ``None``, for cloning without reporting progress.
 """
 
 # -----------------------------------------------------------------------------------

Diff for: git/util.py

@@ -749,7 +749,14 @@ def update(
 
 
 class CallableRemoteProgress(RemoteProgress):
-    """An implementation forwarding updates to any callable."""
+    """A :class:`RemoteProgress` implementation forwarding updates to any callable.
+
+    :note:
+        Like direct instances of :class:`RemoteProgress`, instances of this
+        :class:`CallableRemoteProgress` class are not themselves directly callable.
+        Rather, instances of this class wrap a callable and forward to it. This should
+        therefore not be confused with :class:`git.types.CallableProgress`.
+    """
 
     __slots__ = ("_callable",)