Doc Fixes & Extensions (#2201)

* Add note on dispatcherhandlerstop to conversationhandler

* Fine tune @run_async deprecation warning

* Refine docs of JobQueue.jobs/get_jobs_by_name

telegram/ext/conversationhandler.py

@@ -84,6 +84,8 @@ class ConversationHandler(Handler):
     the conversation ends immediately after the execution of this callback function.
     To end the conversation, the callback function must return :attr:`END` or ``-1``. To
     handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``.
+    Finally, :class:`telegram.ext.DispatcherHandlerStop` can be used in conversations as described
+    in the corresponding documentation.
 
     Note:
         In each of the described collections of handlers, a handler may in turn be a

telegram/ext/dispatcher.py

@@ -67,8 +67,8 @@ def run_async(
     @wraps(func)
     def async_func(*args: Any, **kwargs: Any) -> Any:
         warnings.warn(
-            'The @run_async decorator is deprecated. Use the `run_async` parameter of'
-            '`Dispatcher.add_handler` or `Dispatcher.run_async` instead.',
+            'The @run_async decorator is deprecated. Use the `run_async` parameter of '
+            'your Handler or `Dispatcher.run_async` instead.',
             TelegramDeprecationWarning,
             stacklevel=2,
         )

telegram/ext/jobqueue.py

@@ -498,11 +498,14 @@ class JobQueue:
             self.scheduler.shutdown()
 
     def jobs(self) -> Tuple['Job', ...]:
-        """Returns a tuple of all jobs that are currently in the ``JobQueue``."""
+        """
+        Returns a tuple of all *pending/scheduled* jobs that are currently in the ``JobQueue``.
+        """
         return tuple(Job.from_aps_job(job, self) for job in self.scheduler.get_jobs())
 
     def get_jobs_by_name(self, name: str) -> Tuple['Job', ...]:
-        """Returns a tuple of jobs with the given name that are currently in the ``JobQueue``"""
+        """Returns a tuple of all *pending/scheduled* jobs with the given name that are currently
+        in the ``JobQueue``"""
         return tuple(job for job in self.jobs() if job.name == name)