Merge pull request #68

Enhance JavaDoc comments across multiple interfaces for improved clarity and documentation

Author: marioserrano09

examples/demo-zk-books/src/main/java/mybookstore/repositories/BookRepository.java

@@ -7,10 +7,18 @@
 
 import java.util.Optional;
 
+/**
+ * Repository for {@link Book} entities exposed as a REST resource.
+ */
 @RepositoryRestResource(path = "books")
-
 public interface BookRepository extends JpaRepository<Book, Long> {
 
+    /**
+     * Finds a book by id using a cache-backed lookup.
+     *
+     * @param id the book identifier
+     * @return an optional containing the matching book when found
+     */
     @Override
     @Cacheable(cacheNames = "books", key = "'book_'+#id")
     Optional<Book> findById(Long id);

extensions/dashboard/sources/src/main/java/tools/dynamia/modules/dashboard/UserInfoProvider.java

@@ -19,17 +19,54 @@
 
 import java.util.List;
 
+/**
+ * Provides user identity and authorization data for dashboard runtime decisions.
+ * Implementations are used by widgets and dashboard services to evaluate visibility,
+ * permissions, and user-specific behavior.
+ */
 public interface UserInfoProvider {
 
+    /**
+     * Returns the current authenticated username.
+     *
+     * @return the username associated with the current user context
+     */
     String getUsername();
 
+    /**
+     * Indicates whether the current user has administrative privileges.
+     *
+     * @return {@code true} when the user is an administrator
+     */
     boolean isAdmin();
 
+    /**
+     * Checks if the current user has the specified role.
+     *
+     * @param roleName the role name to verify
+     * @return {@code true} when the user is assigned to the role
+     */
     boolean hasRole(String roleName);
 
+    /**
+     * Checks if the current user has the specified grant/permission.
+     *
+     * @param grant the grant identifier to verify
+     * @return {@code true} when the user has the grant
+     */
     boolean hasGrant(String grant);
 
+    /**
+     * Returns the location identifier associated with the current user.
+     *
+     * @return the user location id, or {@code null} when not applicable
+     */
     Long getUserLocation();
 
+    /**
+     * Returns all role names assigned to the current user.
+     *
+     * @return a list of user role names
+     */
     List<String> getUserRoles();
 }

extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileAccountProvider.java

@@ -21,24 +21,27 @@
 import tools.dynamia.modules.entityfile.domain.EntityFile;
 
 /**
- *
- * @author Mario Serrano Leones
+ * Resolves tenant/account context for entity-file operations.
+ * Implementations provide the current account id and can validate whether
+ * a specific {@link EntityFile} belongs to a valid account scope.
  */
 public interface EntityFileAccountProvider {
 
     /**
-     * Return current account Id for tenant
+     * Returns the current tenant account identifier.
      *
-     * @return account id
+     * @return the current account id
      */
     Long getAccountId();
 
 
     /**
-     * Check is the account id is valid, by default just validate if account id not null
+     * Validates whether the given entity file has a usable account id.
+     * The default implementation checks that the entity file is not null,
+     * account id is not null, and account id is greater than zero.
      *
-     * @param entityFile
-     * @return valid
+     * @param entityFile the entity file to validate
+     * @return {@code true} when the file has a valid account id
      */
     default boolean isValidEntityFile(EntityFile entityFile) {
         return entityFile != null && entityFile.getAccountId() != null && entityFile.getAccountId() > 0;

extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileStorage.java

@@ -19,18 +19,55 @@
 
 import tools.dynamia.modules.entityfile.domain.EntityFile;
 
+/**
+ * Defines the contract for storing and retrieving files associated with domain entities.
+ * Implementations may use local storage, cloud providers, or any custom backend.
+ */
 public interface EntityFileStorage {
 
+    /**
+     * Returns the unique technical identifier of this storage implementation.
+     *
+     * @return the storage identifier, used internally to select the implementation
+     */
     String getId();
 
+    /**
+     * Returns the human-readable name of this storage implementation.
+     *
+     * @return display name for logs, configuration, or UI labels
+     */
     String getName();
 
+    /**
+     * Uploads and persists the provided file information for the given entity file record.
+     *
+     * @param entityFile the entity file metadata to be updated with storage information
+     * @param fileInfo metadata and stream details of the file to upload
+     */
     void upload(EntityFile entityFile, UploadedFileInfo fileInfo);
 
+    /**
+     * Downloads the previously stored file associated with the given entity file record.
+     *
+     * @param entityFile the entity file metadata used to locate the stored file
+     * @return the stored file content and metadata
+     */
     StoredEntityFile download(EntityFile entityFile);
 
+    /**
+     * Deletes the stored file associated with the given entity file record.
+     *
+     * @param entityFile the entity file metadata used to locate and remove the stored file
+     */
     void delete(EntityFile entityFile);
 
+    /**
+     * Reloads storage-specific runtime parameters.
+     * <p>
+     * Implementations can override this method when they need to refresh dynamic
+     * settings (for example, credentials, endpoints, or bucket names) without restart.
+     */
     default void reloadParams(){
 
     }

extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportBeanParser.java

@@ -19,9 +19,20 @@
 
 import org.apache.poi.ss.usermodel.Row;
 
+/**
+ * Functional contract for converting a spreadsheet {@link Row} into a domain object.
+ *
+ * @param <T> the target object type produced from each row
+ */
 @FunctionalInterface
 public interface ImportBeanParser<T> {
 
+	/**
+	 * Parses a spreadsheet row into a typed object.
+	 *
+	 * @param row the row to parse
+	 * @return the parsed object instance
+	 */
 	T parse(Row row);
 
 }

extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportReader.java

@@ -19,9 +19,19 @@
 
 import org.apache.poi.ss.usermodel.Row;
 
+/**
+ * Functional callback invoked for each imported spreadsheet {@link Row}.
+ * Implementations typically perform side effects such as validation,
+ * persistence, or aggregation.
+ */
 @FunctionalInterface
 public interface ImportReader {
 
+	/**
+	 * Processes a spreadsheet row.
+	 *
+	 * @param row the row to process
+	 */
 	void read(Row row);
 
 }

extensions/reports/sources/core/src/main/java/tools/dynamia/modules/reports/core/ReportDataExporter.java

@@ -1,5 +1,17 @@
 package tools.dynamia.modules.reports.core;
 
+/**
+ * Converts {@link ReportData} into a specific output representation.
+ *
+ * @param <T> the exported output type (for example, a map, DTO, or serialized structure)
+ */
 public interface ReportDataExporter<T> {
+
+    /**
+     * Exports the provided report data into the target representation.
+     *
+     * @param reportData the report data to transform
+     * @return the exported representation of the report data
+     */
     T export(ReportData reportData);
 }

extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/IgnoringSecurityMatcher.java

@@ -15,11 +15,17 @@
 package tools.dynamia.modules.security;
 
 /**
- *
- * @author Mario Serrano Leones
+ * Provides request matcher patterns that should bypass security filters.
+ * Implementations are typically used to register public paths such as static
+ * assets, health endpoints, or public APIs.
  */
 public interface IgnoringSecurityMatcher {
 
+    /**
+     * Returns the matcher expressions that must be ignored by security.
+     *
+     * @return an array of path matcher patterns
+     */
     String[] matchers();
 
 }

extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/LoginControllerInterceptor.java

@@ -16,8 +16,20 @@
 import jakarta.servlet.http.HttpServletRequest;
 import java.util.Map;
 
+/**
+ * Intercepts login controller rendering to customize model data or flow.
+ * Implementations can inject additional attributes, flags, or contextual
+ * values before the login view is rendered.
+ */
 public interface LoginControllerInterceptor {
 
+    /**
+     * Called when the login controller is preparing the login page.
+     *
+     * @param request the current HTTP request
+     * @param viewName the view name that will be rendered
+     * @param params mutable model parameters for the login view
+     */
     void login(HttpServletRequest request, String viewName, Map<String, Object> params);
 
 

platform/core/commons/src/main/java/tools/dynamia/commons/Lambdas.java

@@ -14,13 +14,37 @@
 public class Lambdas {
 
 
+    /**
+     * Consumer variant that allows checked exceptions.
+     *
+     * @param <T> the consumed value type
+     */
     @FunctionalInterface
     public interface ThrowingConsumer<T> {
+
+        /**
+         * Performs this operation on the given argument.
+         *
+         * @param t the input argument
+         * @throws Exception if processing fails
+         */
         void accept(T t) throws Exception;
     }
 
+    /**
+     * Supplier variant that allows checked exceptions.
+     *
+     * @param <T> the supplied value type
+     */
     @FunctionalInterface
     public interface ThrowingSupplier<T> {
+
+        /**
+         * Gets a result value.
+         *
+         * @return the supplied value
+         * @throws Exception if value retrieval fails
+         */
         T get() throws Exception;
     }