chg: [skeleton module] added extra explanations

src/Lib/default/local_tool_connectors/SkeletonConnectorExample.php

@@ -90,7 +90,14 @@ class SkeletonConnector extends CommonConnectorTools
             // filter $data
         }
 
-        // return the data embedded in a generic index parameter array
+        /*
+         * return the data embedded in a generic index parameter array
+         * 
+         * For more information on the structure of the index, refer to the cerebrate/src/templates/element/genericElements/IndexTable/index_table.php factory
+         * Valid form field types can be found at cerebrate/src/templates/element/genericElements/IndexTable/Fields
+         * Be aware that some form fields require additional parameters, so make sure that you check the available parameters in the form field template file
+         * 
+         */
 
         return [
             'type' => 'index',
@@ -135,6 +142,14 @@ class SkeletonConnector extends CommonConnectorTools
     public function myFormAction(array $params): array
     {
         if ($params['request']->is(['get'])) {
+            /*
+             * Usually on get requests we return a form to the user
+             * 
+             * This form can either simply be a confirmation prompt (such as the example below), or a full fledged form with diverse form fields
+             * In the latter case, refer to the cerebrate/src/templates/element/Form/genericForm.php library
+             * For individual form field types, see cerebrate/src/templates/element/Form/Fields/*.php
+             * 
+             */
             return [
                 'data' => [
                     'title' => __('My Form Title'),
@@ -146,7 +161,17 @@ class SkeletonConnector extends CommonConnectorTools
                 ]
             ];
         } elseif ($params['request']->is(['post'])) {
-            // handle posted data
+            /*
+             * Handle the posted data here.
+             * The response should be in the following format:
+             * [
+             *   "success": 0|1,
+             *   "message": "your_message_to_the_user"
+             * ]
+             * 
+             * The message can be hard coded or derived from the output of your interactions with the local tool
+             * 
+             */
             if ($success) {
                 return ['success' => 1, 'message' => __('Action successful.')];
             } else {
@@ -164,22 +189,40 @@ class SkeletonConnector extends CommonConnectorTools
 
     public function initiateConnection(array $params): array
     {
-        // encode initial connection in local tool
-        // build and return initiation payload
+        /* 
+         * Encode initial connection in local tool
+         * 
+         * This function is invoked by the REQUESTOR side.
+         * In some cases, this function doesn't interact with the local tool yet, but it is an option that can be handy for 2-way exchanges
+         * Construct the initial payload to be sent to the inbox of the REQUESTEE's Cerebrate node.
+         * 
+         */
         return $payload;
     }
 
     public function acceptConnection(array $params): array
     {
-        // encode acceptance of the connection request in local tool, based on the payload from the initiation
-        // return payload for remote to encode the connection
+        /* 
+         * Encode the actions to be taken if the REQUESTEE accepts the interconnection request
+         * 
+         * The $params parameter will include the payload generated on the REQUESTOR side via the initiateConnection() function
+         * Generate access credentials, configurations, whatever is needed on the REQUESTEE's local tool instance and encode the outcome in the payload
+         * Make sure that the payload includes everything needed by finaliseConnection() to interconnect the REQUESTOR's tool to that of REQUESTEE
+         * 
+         */
         return $payload;
     }
 
     public function finaliseConnection(array $params): bool
     {
-        // based on the payload from the acceptance, finalise the connection
-        // return true on success
+        /* 
+         * Encode the actions to be taken once the positive response from the REQUESTEE arrives back at the REQUESTOR's instance
+         * 
+         * At this point both parties have agreed to the interconnection, REQUESTEE has sent their credentials / access information back to REQUESTOR
+         * The REQUESTOR needs to encode the connection based on the instructions generated by acceptConnection() on the REQUESTEE side
+         * It is sufficient to return true on success.
+         * 
+         */
         return $success;
     }
 }