Enhance documentation for IconsProvider and related classes with detailed descriptions and usage examples

Author: marioserrano09

platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/AbstractFontIconsProvider.java

@@ -27,19 +27,80 @@
 import java.util.Properties;
 
 /**
- * IconsProvider for Fonts Icons
+ * Abstract base class for IconsProvider implementations that serve font-based icons.
+ * This class provides common functionality for loading and managing icon sets from font libraries
+ * such as FontAwesome, Material Icons, or other web font icon systems.
  *
- * @author Mario
+ * <p>Font icons are lightweight, scalable, and customizable through CSS. This provider manages
+ * the mapping between logical icon names and their internal font class names or Unicode values.</p>
+ *
+ * <p>Subclasses must implement {@link #getNamesMapping()} to provide a Properties object
+ * that maps logical icon names to their internal font-specific identifiers.</p>
+ *
+ * <p>The initialization process:</p>
+ * <ul>
+ *   <li>Loads icon name mappings from the Properties returned by getNamesMapping()</li>
+ *   <li>Creates Icon objects with IconType.FONT for each mapping</li>
+ *   <li>Stores icons in an internal cache for quick retrieval</li>
+ *   <li>Logs the installation progress for debugging</li>
+ * </ul>
+ *
+ * <p>Example implementation:</p>
+ * <pre>{@code
+ * @Component
+ * public class FontAwesomeProvider extends AbstractFontIconsProvider {
+ *
+ *     @Override
+ *     public Properties getNamesMapping() {
+ *         Properties props = new Properties();
+ *         props.setProperty("save", "fa-save");
+ *         props.setProperty("edit", "fa-edit");
+ *         props.setProperty("delete", "fa-trash");
+ *         return props;
+ *     }
+ * }
+ * }</pre>
+ *
+ * @author Mario A. Serrano Leones
+ * @see IconsProvider
+ * @see Icon
+ * @see IconType
  */
 public abstract class AbstractFontIconsProvider implements IconsProvider {
 
+    /**
+     * Internal cache storing all loaded icons by their logical name.
+     */
     private final Map<String, Icon> icons = new HashMap<>();
+
+    /**
+     * Logging service for reporting icon loading progress and issues.
+     */
     private final LoggingService logger = new SLF4JLoggingService(getClass());
 
+    /**
+     * Constructs a new AbstractFontIconsProvider and automatically initializes
+     * the icon mappings by calling {@link #init()}.
+     */
     public AbstractFontIconsProvider() {
         init();
     }
 
+    /**
+     * Initializes the icon provider by loading all icon mappings.
+     * This method retrieves the Properties from {@link #getNamesMapping()},
+     * iterates through all entries, and creates Icon objects for each mapping.
+     *
+     * <p>The initialization process:</p>
+     * <ul>
+     *   <li>Obtains the Properties object from the subclass</li>
+     *   <li>Logs the number of icons being installed</li>
+     *   <li>Iterates through each property entry</li>
+     *   <li>Creates a new Icon with IconType.FONT for each mapping</li>
+     *   <li>Stores the icon in the internal cache</li>
+     *   <li>Logs successful completion</li>
+     * </ul>
+     */
     private void init() {
         Properties names = getNamesMapping();
         if (names != null) {
@@ -56,10 +117,26 @@ private void init() {
         }
     }
 
+    /**
+     * Factory method for creating Icon instances.
+     * Subclasses can override this method to customize how Icon objects are created,
+     * for example to add additional metadata or use custom Icon subclasses.
+     *
+     * @param name the logical name of the icon (e.g., "save", "edit")
+     * @param internalName the internal font-specific identifier (e.g., "fa-save", "md-edit")
+     * @return a new Icon instance configured for font-based rendering
+     */
     protected Icon newIcon(String name, String internalName) {
         return new Icon(name, internalName, IconType.FONT);
     }
 
+    /**
+     * Retrieves a font icon by its logical name.
+     * If the icons cache is empty, triggers initialization automatically.
+     *
+     * @param name the logical name of the icon to retrieve
+     * @return the Icon object if found, or null if not available in this provider
+     */
     @Override
     public Icon getIcon(String name) {
         if (icons.isEmpty()) {
@@ -69,13 +146,50 @@ public Icon getIcon(String name) {
         return icons.get(name);
     }
 
+    /**
+     * Provides the mapping between logical icon names and font-specific identifiers.
+     * Subclasses must implement this method to supply their icon set configuration.
+     *
+     * <p>The Properties object should contain entries where:</p>
+     * <ul>
+     *   <li>Key: logical icon name used throughout the application (e.g., "save", "edit")</li>
+     *   <li>Value: font-specific CSS class or identifier (e.g., "fa-save", "md-edit")</li>
+     * </ul>
+     *
+     * <p>Example:</p>
+     * <pre>{@code
+     * Properties props = new Properties();
+     * props.setProperty("save", "fa-floppy-disk");
+     * props.setProperty("edit", "fa-pen-to-square");
+     * props.setProperty("delete", "fa-trash-can");
+     * return props;
+     * }</pre>
+     *
+     * @return a Properties object containing icon name mappings, or null if no icons are available
+     */
     public abstract Properties getNamesMapping();
 
+    /**
+     * Returns all icons provided by this font icon provider.
+     * The returned list is a copy of the internal cache values.
+     *
+     * @return a list containing all font icons managed by this provider
+     */
     @Override
     public List<Icon> getAll() {
         return new ArrayList<>(icons.values());
     }
 
+    /**
+     * Manually adds an icon to this provider's cache.
+     * This method allows runtime addition of icons without requiring them to be
+     * defined in the Properties returned by {@link #getNamesMapping()}.
+     *
+     * <p>Useful for dynamically registering icons or overriding existing ones.</p>
+     *
+     * @param name the logical name for the icon
+     * @param icon the Icon object to register
+     */
     public void addIcon(String name, Icon icon) {
         icons.put(name, icon);
     }

platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/AbstractIconsProvider.java

@@ -29,19 +29,107 @@
 import java.util.Map;
 
 /**
+ * Abstract base class for IconsProvider implementations that serve image-based icons.
+ * This class provides common functionality for loading and managing icon sets from file resources
+ * such as PNG, SVG, GIF, or other image formats stored in the classpath.
+ *
+ * <p>Image-based icons are loaded from a conventional directory structure under the classpath:
+ * {@code classpath:web/{prefix}/16/*.{extension}}. The provider scans this directory at initialization
+ * and automatically registers all icons found.</p>
+ *
+ * <p>Subclasses must implement two methods to configure the icon location:</p>
+ * <ul>
+ *   <li>{@link #getPrefix()}: Defines the subdirectory name under web/ where icons are located</li>
+ *   <li>{@link #getExtension()}: Specifies the file extension of the icon images</li>
+ * </ul>
+ *
+ * <p>The initialization process:</p>
+ * <ul>
+ *   <li>Constructs the classpath pattern using prefix and extension</li>
+ *   <li>Scans the directory for matching resources</li>
+ *   <li>Creates Icon objects for each found resource</li>
+ *   <li>Caches icons in an internal map for quick retrieval</li>
+ *   <li>Logs the installation progress and any errors</li>
+ * </ul>
+ *
+ * <p>Example implementation:</p>
+ * <pre>{@code
+ * @Component
+ * public class SilkIconsProvider extends AbstractIconsProvider {
+ *
+ *     @Override
+ *     public String getPrefix() {
+ *         return "silk"; // Icons in classpath:web/silk/16/*.png
+ *     }
+ *
+ *     @Override
+ *     public String getExtension() {
+ *         return "png";
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>Expected directory structure:</p>
+ * <pre>
+ * src/main/resources/
+ *   web/
+ *     silk/           (prefix)
+ *       16/           (fixed size directory)
+ *         save.png    (icon files with extension)
+ *         edit.png
+ *         delete.png
+ * </pre>
  *
  * @author Mario A. Serrano Leones
+ * @see IconsProvider
+ * @see Icon
+ * @see IconType
  */
 public abstract class AbstractIconsProvider implements IconsProvider {
 
+	/**
+	 * Logging service for reporting icon loading progress and errors.
+	 */
 	private final LoggingService logger = new SLF4JLoggingService(getClass());
+
+	/**
+	 * Internal cache storing all loaded icons by their name (without extension).
+	 */
 	private final Map<String, Icon> icons = new HashMap<>();
+
+	/**
+	 * List containing all loaded icons for quick retrieval.
+	 */
 	private final List<Icon> all = new ArrayList<>();
 
+	/**
+	 * Constructs a new AbstractIconsProvider and automatically initializes
+	 * the icon set by scanning the classpath directory.
+	 */
 	public AbstractIconsProvider() {
 		init();
 	}
 
+	/**
+	 * Initializes the icon provider by scanning and loading icon resources from the classpath.
+	 * This method builds the resource path using the prefix and extension provided by subclasses,
+	 * scans for matching resources, and creates Icon objects for each found file.
+	 *
+	 * <p>The scanning process:</p>
+	 * <ul>
+	 *   <li>Constructs the classpath pattern: {@code classpath:web/{prefix}/16/*.{extension}}</li>
+	 *   <li>Logs the installation path for debugging</li>
+	 *   <li>Uses IOUtils to scan for matching resources</li>
+	 *   <li>Warns if no icons are found in the directory</li>
+	 *   <li>Iterates through found resources and extracts icon names from filenames</li>
+	 *   <li>Creates Icon objects with IconType.IMAGE for each resource</li>
+	 *   <li>Stores icons in both the cache map and the complete list</li>
+	 *   <li>Logs successful completion or errors</li>
+	 * </ul>
+	 *
+	 * <p>The icon name is derived from the filename without its extension.
+	 * For example, {@code save.png} becomes an icon with name {@code "save"}.</p>
+	 */
 	private void init() {
 		String prefix = getPrefix();
 		String extension = getExtension();
@@ -69,10 +157,51 @@ private void init() {
 		}
 	}
 
+	/**
+	 * Returns the prefix (subdirectory name) where icons are located under the web/ directory.
+	 * This prefix is used to construct the classpath resource pattern for icon scanning.
+	 *
+	 * <p>The prefix defines the icon set name and should match the directory structure:
+	 * {@code src/main/resources/web/{prefix}/16/}</p>
+	 *
+	 * <p>Examples:</p>
+	 * <ul>
+	 *   <li>"silk" for Silk icon set → {@code web/silk/16/*.png}</li>
+	 *   <li>"fugue" for Fugue icon set → {@code web/fugue/16/*.png}</li>
+	 *   <li>"custom" for custom icons → {@code web/custom/16/*.svg}</li>
+	 * </ul>
+	 *
+	 * @return the prefix (subdirectory name) for the icon set
+	 */
 	public abstract String getPrefix();
 
+	/**
+	 * Returns the file extension for icon image files (without the leading dot).
+	 * This extension is used to filter icon resources during directory scanning.
+	 *
+	 * <p>Common extensions include:</p>
+	 * <ul>
+	 *   <li>"png" for PNG images (most common)</li>
+	 *   <li>"svg" for SVG vector graphics</li>
+	 *   <li>"gif" for GIF images</li>
+	 *   <li>"jpg" or "jpeg" for JPEG images</li>
+	 * </ul>
+	 *
+	 * @return the file extension without the leading dot (e.g., "png", "svg", "gif")
+	 */
 	public abstract String getExtension();
 
+	/**
+	 * Retrieves an image icon by its logical name.
+	 * If the icons cache is empty, triggers initialization automatically.
+	 *
+	 * <p>The name should match the filename (without extension) of an icon in the
+	 * configured directory. For example, if {@code save.png} exists in the icon directory,
+	 * use "save" as the name parameter.</p>
+	 *
+	 * @param name the logical name of the icon (filename without extension)
+	 * @return the Icon object if found, or null if not available in this provider
+	 */
 	@Override
 	public Icon getIcon(String name) {
 		if (icons.isEmpty()) {
@@ -81,6 +210,12 @@ public Icon getIcon(String name) {
 		return icons.get(name);
 	}
 
+	/**
+	 * Returns all image icons provided by this icon provider.
+	 * The returned list contains all icons discovered during initialization.
+	 *
+	 * @return a list containing all image icons managed by this provider
+	 */
 	@Override
 	public List<Icon> getAll() {
 		return all;