feat(docs): warning on overriding on_connect (#1689)

* feat(docs): warning on overriding on_connect

* fix: broken reference

* feat: example of overriding on_connect

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: BobDotCom <71356958+BobDotCom@users.noreply.github.com>
Co-authored-by: Lala Sabathil <lala@pycord.dev>

discord/bot.py

@@ -645,7 +645,15 @@ async def sync_commands(
         register all commands.
 
         By default, this coroutine is called inside the :func:`.on_connect` event. If you choose to override the
-        :func:`.on_connect` event, then you should invoke this coroutine as well.
+        :func:`.on_connect` event, then you should invoke this coroutine as well such as the follwing:
+
+        .. code-block:: python
+
+            @bot.event
+            async def on_connect():
+                if bot.auto_sync_commands:
+                    await bot.sync_commands()
+                print(f"{bot.user.name} connected.")
 
         .. note::
             If you remove all guild commands from a particular guild, the library may not be able to detect and update
@@ -1500,7 +1508,7 @@ class Bot(BotBase, Client):
 
         .. versionadded:: 2.0
     auto_sync_commands: :class:`bool`
-        Whether to automatically sync slash commands. This will call sync_commands in on_connect, and in
+        Whether to automatically sync slash commands. This will call :meth:`~.Bot.sync_commands` in :func:`discord.on_connect`, and in
         :attr:`.process_application_commands` if the command is not found. Defaults to ``True``.
 
         .. versionadded:: 2.0

docs/api.rst

@@ -572,6 +572,11 @@ Connection
 
     The warnings on :func:`on_ready` also apply.
 
+    .. warning::
+
+        Overriding this event will not call :meth:`Bot.sync_commands`.
+        As a result, :class:`ApplicationCommand` will not be registered.
+
 .. function:: on_shard_connect(shard_id)
 
     Similar to :func:`on_connect` except used by :class:`AutoShardedClient`