Clarify usage of humanize_timedelta (#3000)

- resolves #2986

changelog.d/2986.docs.rst

@@ -0,0 +1 @@
+Added more information about ``redbot.core.utils.humanize_timedelta`` into the docs

changelog.d/2986.misc.rst

@@ -0,0 +1 @@
+Updated the typing of ``redbot.core.utils.humanize_timedelta`` to be more accurate.

redbot/core/utils/chat_formatting.py

@@ -1,6 +1,6 @@
 import itertools
 import datetime
-from typing import Sequence, Iterator, List, Optional, Union
+from typing import Sequence, Iterator, List, Optional, Union, SupportsInt
 from io import BytesIO
 
 
@@ -401,10 +401,32 @@ def format_perms_list(perms: discord.Permissions) -> str:
 
 
 def humanize_timedelta(
-    *, timedelta: Optional[datetime.timedelta] = None, seconds: Optional[int] = None
+    *, timedelta: Optional[datetime.timedelta] = None, seconds: Optional[SupportsInt] = None
 ) -> str:
     """
-    Get a human timedelta representation
+    Get a locale aware human timedelta representation.
+
+    This works with either a timedelta object or a number of seconds.
+
+    Fractional values will be omitted, and values less than 1 second
+    an empty string.
+
+    Parameters
+    ----------
+    timedelta: Optional[datetime.timedelta]
+        A timedelta object
+    seconds: Optional[SupportsInt]
+        A number of seconds
+
+    Returns
+    -------
+    str
+        A locale aware representation of the timedelta or seconds.
+
+    Raises
+    ------
+    ValueError
+        The function was called with neither a number of seconds nor a timedelta object
     """
 
     try: