From 3f035b6d2b6f3f0f2da08db9760428a82845d749 Mon Sep 17 00:00:00 2001
From: Vasileios Karakasis <vkarak@gmail.com>
Date: Thu, 15 Dec 2022 22:57:35 +0100
Subject: [PATCH] Document the rest of `Job`'s properties

---
 docs/regression_test_api.rst        |  6 +++---
 reframe/core/schedulers/__init__.py | 22 +++++++++++++++++++++-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/regression_test_api.rst b/docs/regression_test_api.rst
index bd893f1388..660b05b29d 100644
--- a/docs/regression_test_api.rst
+++ b/docs/regression_test_api.rst
@@ -206,9 +206,9 @@ Environments and Systems
    :members:
    :show-inheritance:
 
--------------------------------------
-Job Schedulers and Parallel Launchers
--------------------------------------
+---------------------------
+Jobs and Parallel Launchers
+---------------------------
 
 .. automodule:: reframe.core.schedulers
    :members:
diff --git a/reframe/core/schedulers/__init__.py b/reframe/core/schedulers/__init__.py
index bdc9470301..28424b186a 100644
--- a/reframe/core/schedulers/__init__.py
+++ b/reframe/core/schedulers/__init__.py
@@ -22,7 +22,10 @@
 
 
 class JobMeta(RegressionTestMeta, abc.ABCMeta):
-    '''Job metaclass.'''
+    '''Job metaclass.
+
+    :meta private:
+    '''
 
 
 class JobSchedulerMeta(abc.ABCMeta):
@@ -354,34 +357,45 @@ def create(cls, scheduler, launcher, *args, **kwargs):
 
     @property
     def name(self):
+        '''The name of this job.'''
         return self._name
 
     @property
     def workdir(self):
+        '''The working directory for this job.'''
         return self._workdir
 
     @property
     def cli_options(self):
+        '''The scheduler options passed through the :option:`-J` command line
+        options.'''
         return self._cli_options
 
     @property
     def script_filename(self):
+        '''The filename of the generated job script.'''
         return self._script_filename
 
     @property
     def stdout(self):
+        '''The file where the standard output of the job is saved.'''
         return self._stdout
 
     @property
     def stderr(self):
+        '''The file where the standard error of the job is saved.'''
         return self._stderr
 
     @property
     def sched_flex_alloc_nodes(self):
+        '''The argument of the :option:`--flex-alloc-nodes` command line
+        option.'''
         return self._sched_flex_alloc_nodes
 
     @property
     def sched_access(self):
+        '''The partition's :attr:`~config.systems.partitions.access`
+        options.'''
         return self._sched_access
 
     @property
@@ -408,10 +422,16 @@ def completion_time(self):
 
     @property
     def scheduler(self):
+        '''The scheduler where this job is assigned to.'''
         return self._scheduler
 
     @property
     def exception(self):
+        '''The last exception that this job encountered.
+
+        The scheduler will raise this exception the next time the status of
+        this job is queried.
+        '''
         return self._exception
 
     @property