From 38110c2868468e616b7c5d6802c183ab1def4bcc Mon Sep 17 00:00:00 2001
From: Oliver Gorwits <oliver@cpan.org>
Date: Sun, 26 Nov 2017 15:07:43 +0000
Subject: [PATCH] update docs in Status

---
 lib/App/Netdisco/Backend/Job.pm   | 18 ++++++++++++++++++
 lib/App/Netdisco/Worker/Status.pm | 14 +++++++++-----
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/lib/App/Netdisco/Backend/Job.pm b/lib/App/Netdisco/Backend/Job.pm
index 16a09c02..a3ffa250 100644
--- a/lib/App/Netdisco/Backend/Job.pm
+++ b/lib/App/Netdisco/Backend/Job.pm
@@ -174,6 +174,10 @@ sub add_status {
 
 =head1 ADDITIONAL COLUMNS
 
+Columns which exist in this class but are not in
+L<App::Netdisco::DB::Result::Admin> class.
+
+
 =head2 id
 
 Alias for the C<job> column.
@@ -186,6 +190,20 @@ sub id { (shift)->job }
 
 Alias for the C<subaction> column.
 
+=head2 only_namespace
+
+Action command from the user can be an action name or the action name plus one
+child namespace in the form: "C<action::child>". This slot stores the C<child>
+component of the command so that C<action> is backwards compatible with
+Netdisco.
+
+=head2 job_priority
+
+When selecting jobs from the database, some types of job are higher priority -
+usually those submitted in the web interface by a user, and those making
+changes (writing to) the device. This slot stores a number which is the
+priority of the job and is used by L<MCE> when managing its job queue.
+
 =cut
 
 sub extra { (shift)->subaction }
diff --git a/lib/App/Netdisco/Worker/Status.pm b/lib/App/Netdisco/Worker/Status.pm
index 1bc741cc..eeae6570 100644
--- a/lib/App/Netdisco/Worker/Status.pm
+++ b/lib/App/Netdisco/Worker/Status.pm
@@ -26,23 +26,27 @@ The status can be:
 
 =item * C<done>
 
-success and this could be the outcome of the action
+Indicates a state of success and a log message which may be used as the
+outcome for the action.
 
 =item * C<info>
 
-success and notable but not the main goal of the action
+The worker has completed successfully and a debug log will be issued, but the
+outcome is not the main goal of the action.
 
 =item * C<defer>
 
-failed to connect, should increment defer counters
+Issued when the worker has failed to connect to the remote device, or is not
+permitted to connect (through user config).
 
 =item * C<error>
 
-had a problem and was unsuccessful
+Something went wrong which should not normally be the case.
 
 =item * C<()>
 
-skipped the worker for some reason but not fatal
+This is not really a status. The worker can return any value not an instance
+of this class to indicate a "pass", or non-error conclusion.
 
 =back