Item14237: More docs on v3 concepts

Minor corrections

core/data/System/ChainedExecutionFlow.txt

@@ -0,0 +1,72 @@
+%META:TOPICINFO{author="ProjectContributor" date="1507254269" format="1.1" version="1"}%
+%META:TOPICPARENT{name="FoswikiV3Essentials"}%
+---+ Chained Calls
+
+There are two techniques used by Foswiki which are using call chaining. These
+are callbacks and extensions. Though their implementations are somewhat
+different but the basic concept remains the same:
+
+   : <em>If there is a point in the code where several actors wanna participate
+   in the code execution by registering special subroutines then those
+   subroutines are gonna be called in a specific order.</em>
+
+In the above definition we're saying nothing about neither the order nor about
+the result of the execution because both are determined by particular technique.
+What is important here is how the calls are chained and how the execution is 
+controlled.
+
+The first principle of call chaining in Foswiki says that everybody must be
+cooperative. The core provides some high level of freedom for the registering
+clients but expects them to behave nicely, responsible and share the playground.
+
+The second principle also explains why the first one is important: everybody has
+the right to control the execution order by either breaking the chain or
+requesting the managing code to restart it from the beginning.
+
+Another thing to remember is that there is always some data which is passed to
+the registered subroutines. Usually in a form of a hasref which is common to
+all subs being called. It means that any changes in the data done by an actor
+will then be passed on to all subsequent actors.
+
+For example, let's imagine we have actors A,B,C,D (how original, isn't it? ;)
+). They're all registered for the same callback. Let's assume that the order
+is alphabetical. Then normally they would be called:
+
+<verbatim>
+A -> B -> C -> D -> core
+</verbatim>
+
+But at some point C decides that something is wrong with the data it received
+and it has to corrected and the whole chain be repeated with the correction
+in hands. It does the changes and raises =Foswiki::Exception::Ext::Restart=:
+
+<verbatim>
++--------+
+v        |
+A-> B -> C -> D -> core
+</verbatim>
+
+Obviously, D is not called during the first chain run; but it has good chances
+to get into action on the second one – unless a bug in C would loop the whole
+thing again and again, until the manager decides that this is no good and
+would fail with a fatal exception.
+
+BTW, restarts are recorded and the information is passed on to the subs making
+it possible for them to make decisions about what to do in this situation.
+
+Breaking the chain looks like this:
+
+<verbatim>
+    +--------->
+    |
+A-> B -> C -> D -> core
+</verbatim>
+
+I.e. C and D will not be called if B decides that there is nothing more to be
+done here. What happens next depends on the technique and documented in
+corresponding documentations.
+
+---++ Related
+
+=%PERLDOC{Foswiki::Callbacks}%=, =%PERLDOC{Foswiki::ExtManager}%=
+

core/data/System/EngineRevisedV3.txt

@@ -0,0 +1,33 @@
+%META:TOPICINFO{author="ProjectContributor" date="1507250413" format="1.1" version="1"}%
+%META:TOPICPARENT{name="FoswikiV3Essentials"}%
+---+ Engine role in Foswiki v3
+
+Introduction of application object concept led to another change in the core
+concepts of Foswiki: engine's role has been revised and cleaned from nonrelevant
+functionality. Now an engine is an abstraction layer between a web server
+environment and Foswiki core. In other words, it's a driver. It is responsible
+for providing the core with necessary data in a unified form, as documented in
+=%PERLDOC{Foswiki::Engine}%=; and it is also provides the results of Foswiki
+core work back to the web server.
+
+From application/core object relations point of view an engine stays somewhat
+aside from other objects as it is usually undesirable to create a new engine
+object via direct call to =create()= method; static method
+=%PERLDOC{"Foswiki::Engine" method="start"}%= must be used instead. It returns
+a (hopefully) valid engine object which type corresponds to the working
+environment.
+
+%X% *NOTE:* Assuming that we currently rely upon
+=[[CPAN:Plack::Handler][Plack::Handler]]= the most probable engine to be used
+would be =%PERLDOC{Foswiki::Engine::PSGI}%=.
+
+An engine object communicates with the rest of the code by providing a set of
+attributes with predefined data formats where information obtained from the web
+server can be found by clients (and =%PERLDOC{Foswiki::Request}%= is the most
+important of them). Back from the core it expects data in PSGI format which is
+now the standard.
+
+---++ Related
+
+=%PERLDOC{Foswiki::Engine}%=
+

core/data/System/FoswikiV3Essentials.txt

@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1507086384" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1507256707" format="1.1" version="1"}%
 %META:TOPICPARENT{name="DeveloperDocumentationCategory"}%
 ---+ Foswiki v3 Essentials
 %TOC%
@@ -12,6 +12,8 @@ Basically, what makes v3 different from all previous versions are:
    first call of =%PERLDOC{"Foswiki::App" method="run"}%= method.
    $ Application centric : Everything in the new core is summoned and
    manipulated by a single application object.
+   $ Engines reconsidered : Engine role in the core ecosystem has been slightly
+   revised.
    $ PSGI support : Yes, the new code is PSGI compliant. Basically, it is the
    main and only mode of operation now. Any other environments like CGI, FastCGI,
    etc. are now supported through corresponding CPAN:Plack::Handler adapters.
@@ -43,8 +45,14 @@ There are some under the hood changes in behaviour of some components like
 ---++ Basic concepts
 
    $ [[OOCodeConcepts]] : Main concepts of programming under %WIKITOOLNAME% v3.
+   $ [[EngineRevisedV3]] : Engine new role in Foswiki V3.
+   $ [[ChainedExecutionFlow]] : Callbacks and extensions chaining of calls.
 
 ---++ New standards
 
    $ [[SpecFileFormat]] : Config Specs v2
 
+---++ Testing
+
+   $ [[FoswikiV3Testing]] : Code testing
+

core/lib/Foswiki/App.pm

@@ -117,6 +117,7 @@ features_provided
     2.99, undef, undef,
     -desc     => "Perl Specs",
     -proposal => "OOConfigSpecsFormat",
+    -doc      => 'SpecFileFormat',
   ],
   ;
 

core/lib/Foswiki/Engine/PSGI.pm

@@ -6,7 +6,8 @@
 
 Class that implements default PSGI behavior.
 
-Refer to Foswiki::Engine documentation for explanation about methods below.
+Refer to %PERLDOC{Foswiki::Engine}% documentation for explanation about methods
+below.
 
 =cut
 

core/lib/Foswiki/ExtManager.pm

@@ -1639,9 +1639,9 @@ sub registerPlugMethod {
 
 =begin TML
 
----++ SEE ALSO
+---++ RELATED
 
-=Foswiki::Extension::Empty=, =Foswiki::Class=.
+=%PERLDOC{Foswiki::Extension::Empty}%=, =%PERLDOC{Foswiki::Class}%=.
 
 =cut