improve documentation and icons handling#50
Conversation
…iled descriptions and usage examples
…sage examples, and method explanations
…oving documentation for icon resolution strategies
…s for improved functionality and clarity
There was a problem hiding this comment.
Pull request overview
This pull request bumps the framework version from 26.2.0 to 26.2.1 and focuses on improving documentation and enhancing icon handling capabilities across the Dynamia Tools framework. The changes add comprehensive Javadoc documentation to many core classes, introduce a new icon configuration feature that supports CSS class specifications, and expand the FontAwesome icon mappings with 492 additional icon aliases.
Changes:
- Version update from 26.2.0 to 26.2.1 across all POM files
- Addition of comprehensive Javadoc documentation with examples to icon-related classes, UI utilities, navigation controllers, and view builder classes
- Introduction of IconName record for representing icons with associated CSS classes
- Enhanced icon parsing functionality supporting pipe-separated format (iconName|class1,class2)
- Extended FontAwesome icon mappings with 492 new icon aliases covering UI, restaurant, and POS domains
- Refactored EnumIconImage to support icon CSS classes
- Updated ZKUtil.configureComponentIcon to accept extra CSS classes
- Replaced obsolete AppTest with new IconTest
- Minor documentation fix in ExporterFieldLoader
Reviewed changes
Copilot reviewed 72 out of 72 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| pom.xml (root + multiple modules) | Version bump from 26.2.0 to 26.2.1 across all modules |
| platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/IconName.java | New record class for icon name with CSS classes |
| platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/Icons.java | Added parseIconName/parseIconNames methods and comprehensive Javadoc |
| platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/*.java | Added extensive Javadoc to IconsTheme, IconsProvider, Icon, IconSize, and related classes |
| platform/ui/ui-shared/src/main/java/tools/dynamia/ui/icons/Abstract*.java | Added detailed Javadoc to AbstractIconsProvider and AbstractFontIconsProvider |
| platform/ui/zk/src/main/java/tools/dynamia/zk/ui/FontAwesomeIconsProvider.java | Added comprehensive Javadoc with examples |
| platform/ui/zk/src/main/java/tools/dynamia/zk/util/ZKUtil.java | Enhanced configureComponentIcon to support extra CSS classes |
| platform/ui/zk/src/main/java/tools/dynamia/zk/ui/EnumIconImage.java | Updated to use IconName and support CSS classes |
| platform/ui/zk/src/main/resources/META-INF/dynamia/fa-icons.properties | Added 492 new icon mappings |
| platform/ui/ui-shared/src/test/java/tools/dynamia/ui/IconTest.java | New test for icon name parsing |
| platform/ui/ui-shared/src/test/java/tools/dynamia/ui/AppTest.java | Removed obsolete placeholder test |
| platform/ui/ui-shared/src/main/java/tools/dynamia/ui/*.java | Added Javadoc to UITools, MessageType, Form classes |
| platform/core/viewers/src/main/java/tools/dynamia/viewers/ViewDescriptorBuilder.java | Added comprehensive Javadoc for builder pattern methods |
| platform/core/web/src/main/java/tools/dynamia/web/navigation/*.java | Added Javadoc to navigation controllers and configuration classes |
| platform/core/reports/src/main/java/tools/dynamia/reports/ExporterFieldLoader.java | Fixed documentation reference |
| * <pre>{@code | ||
| * iconImage.setIconsNames("check-circle, clock, times-circle"); | ||
| * }</pre> |
There was a problem hiding this comment.
The Javadoc formatting has excessive indentation for the code example. The example code block starting at line 121 has irregular spacing/indentation that makes it difficult to read. Consider using standard indentation for better code presentation in the generated Javadoc.
| * return user.isActive() ? "Active" : "Inactive"; | ||
| * default: | ||
| * return BeanUtils.getFieldValue(field, user); | ||
| * return {@link tools.dynamia.commons.ObjectOperations}.getFieldValue(field, user); |
There was a problem hiding this comment.
The Javadoc reference uses {@link tools.dynamia.commons.ObjectOperations} with curly braces around the link, which will create a link in the documentation. However, this is inside a code example block, which might not render correctly. Consider using plain text or @code tag for the class reference within the example, or verify that this rendering is intentional.
| assert iconName.name().equals("edit"); | ||
| assert iconName.classes().size() == 3; | ||
| assert iconName.classes().get(0).equals("red"); | ||
| assert iconName.classes().get(1).equals("blue"); | ||
| assert iconName.classes().get(2).equals("green"); |
There was a problem hiding this comment.
The test method uses plain assert statements instead of JUnit assertions (e.g., assertEquals, assertTrue). While this works, it's better practice to use JUnit's assertion methods for clearer failure messages and better test maintainability. Consider using assertEquals(expected, actual) or assertTrue(condition) from org.junit.Assert.
| package tools.dynamia.ui.icons; | ||
|
|
||
| /** | ||
| * Enumeration representing different sizes for icons in the UI. This enum defines three standard sizes: SMALL, NORMAL, and LARGE, each associated with a specific directory name that can be used to locate the corresponding icon resources. The getDir() method allows retrieval of the directory name for each size, facilitating the organization and access of icon assets based on their intended display size. |
There was a problem hiding this comment.
The Javadoc for IconSize.java is a single, very long line (over 200 characters) which makes it hard to read. According to best practices and the coding guidelines, Javadoc should be formatted with proper line breaks for better readability. Consider breaking this into multiple lines with proper paragraph tags.
| public static IconName parseIconName(String name) { | ||
|
|
||
| if (name == null || name.isBlank()) { | ||
| return new IconName(null, Collections.emptyList()); |
There was a problem hiding this comment.
According to the Javadoc documentation at line 229-231, the method states that it "Returns: null" for null/empty/blank inputs. However, the actual implementation at line 239 returns new IconName(null, Collections.emptyList()) instead of null. This is a discrepancy between documentation and implementation. Either update the documentation to accurately reflect the behavior, or change the implementation to return null as documented.
| public static void configureComponentIcon(String icon, Component component, IconSize size) { | ||
| IconName iconName = Icons.parseIconName(icon); | ||
| configureComponentIcon(IconsTheme.get().getIcon(iconName.name()), component, size, iconName.classes()); |
There was a problem hiding this comment.
Potential NullPointerException: When parseIconName returns an IconName with a null name (for null/empty/blank input), calling iconName.name() at line 856 will return null, which is then passed to IconsTheme.get().getIcon(null). This could lead to unexpected behavior. Consider adding a null check or handling the case where iconName.name() is null.
No description provided.