docs: update arangodb documentation

Signed-off-by: Otavio Santana <[email protected]>

Author: otaviojava

jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java

@@ -20,48 +20,63 @@
 
 import java.util.Map;
 import java.util.stream.Stream;
-
 /**
- * A {@link JNoSQLDocumentTemplate} to arangoDB
+ * A template specialization for ArangoDB that includes capabilities for executing ArangoDB query language, AQL.
+ * This template extends {@link JNoSQLDocumentTemplate} and provides methods for executing AQL queries with various
+ * options.
  */
 public interface ArangoDBTemplate extends JNoSQLDocumentTemplate {
 
     /**
-     * Executes ArangoDB query language, AQL.
-     * <p>FOR u IN users FILTER u.status == @status RETURN u </p>
+     * Executes an ArangoDB query using the ArangoDB Query Language (AQL).
+     *
+     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     *
+     * <p>The conversion from the query result to entities will happen at the Eclipse JNoSQL side.
+     * It will utilize and consider all the annotations supported by Eclipse JNoSQL.</p>
      *
-     * @param <T>    entity class
-     * @param query  the query
-     * @param params the named queries
-     * @return the query result
-     * @throws NullPointerException when either query or params are null
+     * @param <T>    the entity class
+     * @param query  the AQL query
+     * @param params the named parameters for the query
+     * @return a {@link Stream} of entities representing the query result
+     * @throws NullPointerException when either the query or params are null
      */
     <T> Stream<T> aql(String query, Map<String, Object> params);
 
     /**
-     * Executes ArangoDB query language, AQL.
-     * <p>FOR u IN users FILTER u.status == @status RETURN u </p>
+     * Executes an ArangoDB query using the ArangoDB Query Language (AQL).
+     *
+     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     *
+     * <p>The serialization of the query result will happen at the ArangoDB side using
+     * {@link com.arangodb.ArangoDatabase#query(String, Class)}. This serialization does not have any converter support
+     * at the mapper side,
+     * thus it will ignore any annotations that Eclipse JNoSQL has.</p>
      *
-     * @param query     the query
-     * @param params    named query
-     * @param type The type of the result
-     * @param <T>       the type
-     * @return the query result
-     * @throws NullPointerException when either query or params are null
+     * @param query  the AQL query
+     * @param params the named parameters for the query
+     * @param type   the type of the result
+     * @param <T>    the type
+     * @return a {@link Stream} of the specified type representing the query result
+     * @throws NullPointerException when either the query or params are null
      */
     <T> Stream<T> aql(String query, Map<String, Object> params, Class<T> type);
 
     /**
-     * Executes ArangoDB query language, AQL.
-     * <p>FOR u IN users FILTER u.status == @status RETURN u </p>
+     * Executes an ArangoDB query using the ArangoDB Query Language (AQL) with an empty parameter map.
      *
-     * @param query     the query
-     * @param type The type of the result
-     * @param <T>       the type
-     * @return the query result
-     * @throws NullPointerException when either query or values are null
+     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     *
+     * <p>The serialization of the query result will happen at the ArangoDB side using
+     * {@link com.arangodb.ArangoDatabase#query(String, Class)}. This serialization does not have any converter support
+     * at the mapper side,
+     * thus it will ignore any annotations that Eclipse JNoSQL has.</p>
+     *
+     * @param query the AQL query
+     * @param type  the type of the result
+     * @param <T>   the type
+     * @return a {@link Stream} of the specified type representing the query result
+     * @throws NullPointerException when either the query or type are null
      */
     <T> Stream<T> aql(String query, Class<T> type);
-
-
 }