From 91674ac9de9fc285ca1bd29b418ae32e3d213e6d Mon Sep 17 00:00:00 2001
From: Simon Bray <32272674+simonbray@users.noreply.github.com>
Date: Tue, 8 Nov 2022 11:47:09 +0100
Subject: [PATCH] small change to job runner docs

to state more explicitly what `check_watched_item()` should return
---
 doc/source/dev/build_a_job_runner.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/source/dev/build_a_job_runner.rst b/doc/source/dev/build_a_job_runner.rst
index 640d44cb62a..0f0bc9de63b 100644
--- a/doc/source/dev/build_a_job_runner.rst
+++ b/doc/source/dev/build_a_job_runner.rst
@@ -276,7 +276,9 @@ Note:
 
 -  ``get_task_from_external_runner`` and ``create_log_files`` are user-defined methods.
 
--  Return value is ``job_state`` for running, pending jobs and None for any remaining states of a job.
+-  The method should return ``job_state`` if the job should remain in the job runner's list of watched
+   jobs (i.e. if it is running or pending). If it no longer needs to be watched (e.g. it has terminated
+   either successfully or with an error) it should return None.
 
 ``create_log_files()`` are nothing but copying the files (``error_file``,
 ``output_file``, ``exit_code_file``) from the external runner's directory to