From fe5c16a16dc1b8ec15fed170669219e2c6c4501e Mon Sep 17 00:00:00 2001
From: Oliver Gorwits <oliver@cpan.org>
Date: Wed, 30 Aug 2017 20:37:36 +0100
Subject: [PATCH] rework docs to be more clear and reflect new operation

---
 lib/App/Netdisco/Core/Plugin.pm               | 10 ++--
 .../Netdisco/Manual/WritingCoreWorkers.pod    | 60 +++++++++++++++----
 2 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/lib/App/Netdisco/Core/Plugin.pm b/lib/App/Netdisco/Core/Plugin.pm
index 04f0314a..c7136221 100644
--- a/lib/App/Netdisco/Core/Plugin.pm
+++ b/lib/App/Netdisco/Core/Plugin.pm
@@ -109,6 +109,11 @@ Netdisco prepends "C<App::Netdisco::Core::Plugin::>" to any entry in the list.
 For example, "C<Discover::Wireless::UniFi>" will load the
 C<App::Netdisco::Core::Plugin::Discover::Wireless::UniFi> package.
 
+You can prepend module names with "C<X::>" as shorthand for the "Netdisco
+extension" namespace. For example, "C<X::Macsuck::WirelessNodes::UniFi>" will
+load the L<App::NetdiscoX::Core::Plugin::Macsuck::WirelessNodes::UniFi>
+module.
+
 If an entry in the list starts with a "C<+>" (plus) sign then Netdisco attemps
 to load the module as-is, without prepending anything to the name. This allows
 you to have App::Netdiso Core plugins in other namespaces.
@@ -126,10 +131,5 @@ The order of the entries is significant, workers being executed in the order
 which they appear in C<core_plugins> and C<extra_core_plugins> (although see
 L<App::Netdisco::Manual::WritingCoreWorkers> for caveats).
 
-Finally, you can also prepend module names with "C<X::>", to support the
-"Netdisco extension" namespace. For example,
-"C<X::Macsuck::WirelessNodes::UniFi>" will load the
-L<App::NetdiscoX::Core::Plugin::Macsuck::WirelessNodes::UniFi> module.
-
 =cut
 
diff --git a/lib/App/Netdisco/Manual/WritingCoreWorkers.pod b/lib/App/Netdisco/Manual/WritingCoreWorkers.pod
index 5c0f5a61..5c392e00 100644
--- a/lib/App/Netdisco/Manual/WritingCoreWorkers.pod
+++ b/lib/App/Netdisco/Manual/WritingCoreWorkers.pod
@@ -89,6 +89,9 @@ include C<snmp>, C<netconf>, C<restconf>, C<eapi>, and C<cli>. The convention
 is for driver names to be lowercase. Use the driver name to associate
 authentication configuration settings with the correct workers.
 
+A pseudo-driver of C<netdisco> can be used if you won't be connecting to a
+device (such as within the C<Expire> action).
+
 =head2 Optional Parameters
 
 Workers may have C<only> and C<no> parameters configured which use the
@@ -132,11 +135,10 @@ C<core_plugins> so you have an opportunity to override core workers by
 adding them to C<extra_core_plugins> and setting C<hook> to C<on> in the
 worker configuration.
 
-The return code of the worker is ignored for those configured with hook
-C<after>, but is significant for those configured with C<befoe> or C<on>.
-If any worker returns a true value then the group at that phase is
-deemed to have been satisfied and Netdsico will move on to other worker
-plugins.
+The return code of the worker is significant for the C<before> and C<on>
+hooks: when the worker returns true, no other hooks are run for that phase.
+The return code is ignored for C<after> hooks, meaning they all run regardless
+of success.
 
 Remember that a worker is only run if it matches the hardware platform of the
 target device and the user's configuration, and is not also excluded by the
@@ -157,13 +159,49 @@ See the documentation for each transport to find out how to access it:
 
 L<App::Netdisco::Core::Transport::SNMP>
 
-=item *
+=back
 
-L<App::Netdisco::Core::Transport::HTTPS>
+=head2 Review of Terminology
 
-=item *
+In summary, Worker code is defined in a package namespace specifying the
+Action and Phase, and registered as a plugin with configuration specifying the
+Hook and Driver. Some rules and Access Control Lists determine which Workers
+are permitted to run, and when. Here are more complete definitions:
 
-L<App::Netdisco::Core::Transport::SSH>
+=over 4
+
+=item C<action>
+
+The highest level grouping of workers, corresponding to a Netdisco command
+such as C<discover> or C<macsuck>. Hooks can be registered at this level to do
+really early bootstrapping work.
+
+=item C<phase>
+
+The next level down from C<action> for grouping workers. Phases have arbitrary
+names and are visited in the order defined in the C<extra_core_plugins>
+setting list, followed by the C<core_plugins> setting list. Hooks are usually
+registered at this level.
+
+=item C<hook> (defaults to C<after>)
+
+The next level down from C<phase> for grouping workers. C<before> hooks
+are run first (for the action and then all its phases). C<on> and C<after>
+hooks run next. The return code of workers may be significant, depending on
+the hook they are registered to.
+
+=item C<worker>
+
+A lump of code you write which does a single clearly defined task. The package
+namespace of the worker identifies the action and optionally the phase. The
+code within is bound to a given hook when registered as a plugin.
+
+=item C<driver>
+
+A label associated with a group of workers which refers to a combination of
+transport and application protocol used to connect to and communicate with the
+target device. Users may attach authentication configuration to specific
+drivers.
 
 =back
 
@@ -175,7 +213,9 @@ connections to other databases.
 
  # plugin package
  use Dancer::Plugin::DBIC;
- schema('netdisco')->resultset('Devices')->search({vendor => 'cisco'});
+ my $set =
+   schema('netdisco')->resultset('Devices')
+                     ->search({vendor => 'cisco'});
 
 =cut