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 02e1623 WIP Javadoc.
02e1623 is described below
commit 02e162312346ee04b78a0f2089f7aa6ba48c9201
Author: Aaron Radzinski <[email protected]>
AuthorDate: Fri Mar 25 18:16:22 2022 -0700
WIP Javadoc.
---
.../main/scala/org/apache/nlpcraft/NCEntity.java | 27 +++++++++++++++++++---
.../main/scala/org/apache/nlpcraft/NCModel.java | 2 +-
.../main/scala/org/apache/nlpcraft/NCRequest.java | 4 +++-
.../main/scala/org/apache/nlpcraft/NCToken.java | 1 +
.../scala/org/apache/nlpcraft/NCTokenParser.java | 2 +-
5 files changed, 30 insertions(+), 6 deletions(-)
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.java
index ce5fabf..44c7eb3 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.java
@@ -23,12 +23,28 @@ import java.util.Set;
import java.util.stream.Collectors;
/**
+ * An enenity is a collection if one or more {@link NCToken tokens}. An entity
typically has a
+ * consistent semantic meaning and usually denotes a real-world object, such
as persons, locations, number,
+ * date and time, organizations, products, etc. - where such objects can be
abstract or have a physical existence.
+ * Entities are produced by {@link NCEntityParser}. See {@link NCPipeline} for
documentation on the entities in the
+ * overall processing pipeline.
*
+ * <span class="hdr">Metadata</span>
+ * Note that both {@link NCToken} and {@link NCEntity} interfaces extend
{@link NCPropertyMap} interface
+ * that allows them to store custom metadata properties. Parser, enrichers and
validators for tokens
+ * and entities use this capability to store and check their properties in
tokens and entities.
+ *
+ * @see NCToken
+ * @see NCTokenParser
+ * @see NCTokenEnricher
+ * @see NCTokenValidator
+ * @see NCPipeline
*/
public interface NCEntity extends NCPropertyMap {
/**
+ * Gets the list of tokens this entity is comprised of. Ruturned list is
never empty or {@code null}.
*
- * @return
+ * @return List of tokens that are part of this entity.
*/
List<NCToken> getTokens();
@@ -36,6 +52,9 @@ public interface NCEntity extends NCPropertyMap {
* Joins all tokens' text with trimming using space as a delimiter. This
function does not cache the
* result and performs text construction on each call. Make sure to cache
the result to avoid
* unnecessary parasitic workload if and when method {@link #getTokens()}
does not change.
+ *
+ * @return Constructuted textual representation of this entity. Note that
returned value is not
+ * cached and created anew every time this method is called.
*/
default String mkText() {
return getTokens().stream().map(s ->
s.getText().trim()).collect(Collectors.joining(" ")).trim();
@@ -49,14 +68,16 @@ public interface NCEntity extends NCPropertyMap {
String getRequestId();
/**
+ * Gets optional set of groups this entity belongs to.
*
- * @return
+ * @return Optional set of groups this entity belongs to. Returned set can
be empty but never {@code null}.
*/
default Set<String> getGroups() { return Collections.singleton(getId()); }
/**
+ * Gets globally unique ID of this entity.
*
- * @return
+ * @return Globally unique ID of this entity.
*/
String getId();
}
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.java
index 7f262a0..79ae63b 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.java
@@ -34,7 +34,7 @@ package org.apache.nlpcraft;
* some aspects of your data models - your entire model and all of its
components are part of your project's source code.
* <p>
* In most cases, one would use a convenient {@link NCModelAdapter} adapter to
implement this interface. Here's a snippet
- * of the user data model from Lighswitch example:
+ * of the user data model from LightSwitch example:
* <pre class="brush: java, highlight: [1]">
* public class LightSwitchJavaModel extends NCModelAdapter {
* public LightSwitchJavaModel() {
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRequest.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRequest.java
index 9554d1d..17cfa58 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRequest.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRequest.java
@@ -26,7 +26,9 @@ import java.util.Map;
*/
public interface NCRequest {
/**
- * Gets ID of the user on behalf of which this request was submitted.
+ * Gets ID of the user on behalf of which this request was submitted. User
ID is used by
+ * NLPCraft to manage the conversation state. It can be any value as long
as it is constant
+ * and globally unique for the given user.
*
* @return User ID.
*/
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.java
index 6ed7398..6d5aea6 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.java
@@ -19,6 +19,7 @@ package org.apache.nlpcraft;
/**
* Represents a contiguous substring of the original input text produced by
{@link NCTokenParser}.
+ * See {@link NCPipeline} for documentation on the tokens place in the overall
processing pipeline.
*
* <span class="hdr">Metadata</span>
* Note that both {@link NCToken} and {@link NCEntity} interfaces extend
{@link NCPropertyMap} interface
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.java
index 5fb158a..69d3ae1 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.java
@@ -21,7 +21,7 @@ import java.util.List;
/**
* A tokenizer that splits a text into the list of {@link NCToken tokens}.
- *
+ * <p>
* See {@link NCPipeline} for documentation on the token parser place
* in the overall processing pipeline.
*
