[incubator-nlpcraft] branch master updated: WIP scaladoc.

[ar...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

aradzinski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nlpcraft.git


The following commit(s) were added to refs/heads/master by this push:
     new eb216c1c WIP scaladoc.
eb216c1c is described below

commit eb216c1c74c3590f7bfe6a9761f62d721cfed922
Author: Aaron Radzinski <ar...@datalingvo.com>
AuthorDate: Mon Aug 29 13:00:28 2022 -0700

    WIP scaladoc.
---
 .../scala/org/apache/nlpcraft/NCEntityMapper.scala |  5 ++--
 .../scala/org/apache/nlpcraft/NCEntityParser.scala |  2 +-
 .../org/apache/nlpcraft/NCEntityValidator.scala    |  5 ++++
 .../scala/org/apache/nlpcraft/NCFiredIntent.scala  | 28 +++++++++++++---------
 4 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityMapper.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityMapper.scala
index 0948c93c..c6404893 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityMapper.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityMapper.scala
@@ -36,12 +36,13 @@ package org.apache.nlpcraft
   */
 trait NCEntityMapper extends NCLifecycle:
     /**
-      * Maps given of entities into a new list of entities.
+      * Maps given of entities into a new list of entities. Used typically to combine several entities into one
+      * or to introduce a synthetic entity.
       *
       * @param req Input request descriptor.
       * @param cfg Configuration of the model this component is associated with.
       * @param ents List of entities to map.
       * @return List of entities (new or existing ones).
       */
-    def map(req: NCRequest, cfg: NCModelConfig, ents: List[NCEntity]) :List[NCEntity]
+    def map(req: NCRequest, cfg: NCModelConfig, ents: List[NCEntity]): List[NCEntity]
 
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityParser.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityParser.scala
index cd989705..6c111dd7 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityParser.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityParser.scala
@@ -35,7 +35,7 @@ package org.apache.nlpcraft
   */
 trait NCEntityParser extends NCLifecycle:
     /**
-      * Converts, parses, given list of tokens into the list of entities.
+      * Parses and converts given list of tokens into the list of entities.
       *
       * @param req Input request descriptor.
       * @param cfg Configuration of the model this component is associated with.
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityValidator.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityValidator.scala
index ef099f65..359cfb5d 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityValidator.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntityValidator.scala
@@ -22,6 +22,10 @@ package org.apache.nlpcraft
   * See [[NCPipeline]] for documentation on the overall processing pipeline. Note that this is an
   * optional component.
   *
+  * This component can be used to perform any kind of last-stage validation before the list of
+  * entities is passed to intent matching. For example, this can be used for content-based access control, time-based
+  * control, location-based control, etc.
+  *
   * @see [[NCPipeline.getEntityValidators]]
   * @see [[NCEntity]]
   * @see [[NCToken]]
@@ -35,6 +39,7 @@ package org.apache.nlpcraft
   */
 trait NCEntityValidator extends NCLifecycle:
     /**
+      * Validates the final list of parsed and enriched entities.
       *
       * @param req Input request descriptor.
       * @param cfg Configuration of the model this component is associated with.
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCFiredIntent.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCFiredIntent.scala
index 6f7c892c..6c7093c0 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCFiredIntent.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCFiredIntent.scala
@@ -18,25 +18,31 @@
 package org.apache.nlpcraft
 
 /**
-  * 
+  * A descriptor of the intent callback returned by [[NCModelClient.debugAsk()]] method. This descriptor
+  * defines the callback for the intent that was detected as a winning intent but whose callback wasn't
+  * fired as per [[NCModelClient.debugAsk()]] method.
+  *
+  * Using this descriptor the user can execute callback itself, if necessary.
+  *
+  * @see [[NCModelClient.debugAsk()]]
   */
 trait NCFiredIntent:
-    type NCArguments = List[List[NCEntity]]
-
     /**
-      * 
-      * @return
+      * Gets ID of the matched intent.
       */
     def getIntentId: String
 
     /**
-      * 
-      * @return
+      * Gets the list of callback arguments as list of list of entities.
+      *
+      * @see [[getCallback]]
       */
-    def getCallbackArguments: NCArguments
+    def getCallbackArguments: List[List[NCEntity]]
 
     /**
-      * 
-      * @return
+      * Gets the callback function that takes list of list of entities and returns
+      * an instance of [[NCResult]] class.
+      *
+      * @see [[getCallbackArguments]]
       */
-    def getCallback: NCArguments => NCResult
+    def getCallback: List[List[NCEntity]] => NCResult