Update Javadocs and README for localized string docs

Author: glebfox

CHANGELOG.md

@@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ### Added
 
 - Support sorting `LocalizedString` values by the user's current locale.
-- Configuration properties to disable the add-on sorting customizations.
+  - Configuration properties to disable the add-on sorting customizations.
 - Bean Validation annotations for `LocalizedString` values, including locale-aware not-null validation.
 
 ### Changed

README.md

@@ -4,7 +4,7 @@
 
 # Jmix LocalizedString Datatype
 
-This add-on provides a custom [Datatype](https://docs.jmix.io/jmix/data-model/data-types.html) and related action for the [ValuePicker](https://docs.jmix.io/jmix/flow-ui/vc/components/valuePicker.html) component for storing and editing localized string values.
+This add-on provides a custom [Datatype](https://docs.jmix.io/jmix/data-model/data-types.html), sorting support, Bean Validation constraints, and a related action for the [ValuePicker](https://docs.jmix.io/jmix/flow-ui/vc/components/valuePicker.html) component for storing and editing localized string values.
 
 The value displayed in visual components depends on the user's current locale.
 
@@ -19,32 +19,32 @@ The following table shows which version of the add-on is compatible with which v
 |--------------|----------------|----------------------------------------------------------------------|
 | 2.3.0+       | 1.0.0          | com.glebfox.jmix.locstr:jmix-localized-string-datatype-starter:1.0.0 |
 
-For manual installation, add the following dependencies to your `build.gradle`:
+For manual installation, add the following dependency to your `build.gradle`:
 
 ```groovy
 implementation 'com.glebfox.jmix.locstr:jmix-localized-string-datatype-starter:<addon-version>'
 ```
 
-## Using the Addon
+## Using the Add-on
 
-The `LocalizedString` datatype is represented by three classes: 
+The `LocalizedString` datatype is represented by three classes:
 
-* [LocalizedString.java](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/datatype/LocalizedString.java) - custom Java class used as a type of entity attributes. 
+* [LocalizedString.java](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/datatype/LocalizedString.java) - custom Java class used as a type of entity attributes.
 * [LocalizedStringDatatype.java](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/datatype/LocalizedStringDatatype.java) - a `Datatype` implementation class for `LocalizedString`.
 * [LocalizedStringConverter.java](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/datatype/LocalizedStringConverter.java) - a class that converts entity attribute state into database column representation and back again.
 
 You can define an entity attribute with the `LocalizedString` datatype using Studio. For example:
 
 ![Attribute Datatype](/doc/img/attribute-datatype.png)
 
-As a result, Studio generates the following attribute definition: 
+As a result, Studio generates the following attribute definition:
 
 ```java
 @Column(name = "NAME", nullable = false)
 private LocalizedString name;
 ```
 
-To edit localized value, add action with `type="value_localizedStringEdit"` to the `ValuePicker` component. For example:
+To edit a localized value, add an action with `type="value_localizedStringEdit"` to the `ValuePicker` component. For example:
 
 ```xml
 <valuePicker id="nameField" property="name">
@@ -84,7 +84,7 @@ The `value_localizedStringEdit` action is represented by [LocalizedStringEditAct
 
 ### Properties
 
-* `multiline` - sets whether to use a multi-line text input component. `TextArea` is used for multi-line text input, `TextField` otherwise. `false` by default. If an entity attribute is annotated with `@Lob`, multi-line text input is used. For example:
+* `multiline` - sets whether to use a multi-line text input component. `TextArea` is used for multi-line text input, `TextField` otherwise. If the property is not set explicitly and the entity attribute is annotated with `@Lob`, multi-line text input is used. For example:
 
 ```java
 @Lob
@@ -136,12 +136,12 @@ If the target `ValuePicker` of `LocalizedStringEditAction` is bound to a require
 
 The add-on provides Bean Validation annotations for `LocalizedString` attributes:
 
-* `@LocalizedStringSize`
-* `@LocalizedStringLength`
-* `@LocalizedStringPattern`
-* `@LocalizedStringNotNull`
-* `@LocalizedStringNotEmpty`
-* `@LocalizedStringNotBlank`
+* [`@LocalizedStringSize`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringSize.java) checks that every localized value length is between `min` and `max`. A `null` `LocalizedString` is valid.
+* [`@LocalizedStringLength`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringLength.java) checks that every localized value length is between `min` and `max`. A `null` `LocalizedString` is valid.
+* [`@LocalizedStringPattern`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringPattern.java) checks that every localized value matches `regexp`. A `null` `LocalizedString` is valid.
+* [`@LocalizedStringNotNull`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringNotNull.java) checks that a non-null localized value is stored for every configured application locale.
+* [`@LocalizedStringNotEmpty`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringNotEmpty.java) checks that every localized value is not empty. A `null` `LocalizedString` and an empty set of localized values are invalid.
+* [`@LocalizedStringNotBlank`](jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/validation/constraints/LocalizedStringNotBlank.java) checks that every localized value contains at least one non-whitespace character. A `null` `LocalizedString` and an empty set of localized values are invalid.
 
 For example:
 
@@ -152,7 +152,7 @@ For example:
 private LocalizedString name;
 ```
 
-Every stored localized value is validated. `@LocalizedStringNotNull` also checks that a value is stored for every configured application locale. When the edit dialog is used for an entity attribute, these constraints are applied to each locale field separately. Standard `@NotNull` can still be used for the attribute itself when only the `LocalizedString` object reference should be checked.
+When the edit dialog is used for an entity attribute, these constraints are applied to each locale field separately. Standard `@NotNull` can still be used for the attribute itself when only the `LocalizedString` object reference should be checked.
 
 Additionally, you can add a validator that checks the value of every field in the edit dialog. For example:
 
@@ -170,7 +170,7 @@ private void descriptionFieldValidator(final ValidationContext validationContext
 
 ### Field Provider
 
-It's possible tio change edit fields by setting the field provider, which will return a component for a given `FieldGenerationContext`. For example:
+It's possible to change edit fields by setting the field provider, which will return a component for a given `FieldGenerationContext`. For example:
 
 ```java
 @Install(to = "descriptionField.localizedStringEdit", subject = "fieldProvider")

jmix-localized-string-datatype-starter/src/main/java/com/glebfox/jmix/autoconfigure/locstr/LocstrAutoConfiguration.java

@@ -20,8 +20,10 @@
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.context.annotation.Import;
 
+/**
+ * Spring Boot auto-configuration that imports the LocalizedString Jmix module.
+ */
 @AutoConfiguration
 @Import({LocstrConfiguration.class})
 public class LocstrAutoConfiguration {
 }
-

jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/LocstrConfiguration.java

@@ -30,13 +30,25 @@
 
 import java.util.Collections;
 
+/**
+ * Spring configuration that registers the LocalizedString Jmix module.
+ */
 @Configuration
 @ComponentScan
 @ConfigurationPropertiesScan
 @JmixModule(dependsOn = {EclipselinkConfiguration.class, FlowuiConfiguration.class})
 @PropertySource(name = "com.glebfox.jmix.locstr", value = "classpath:/com/glebfox/jmix/locstr/module.properties")
 public class LocstrConfiguration {
 
+    /**
+     * Registers action metadata for add-on UI actions.
+     *
+     * @param applicationContext          Spring application context used by the
+     *                                    Jmix action scanner
+     * @param metadataReaderFactory      metadata reader factory used by the
+     *                                    Jmix action scanner
+     * @return action configuration that scans the add-on action package
+     */
     @Bean("locstr_LocstrActions")
     public ActionsConfiguration actions(final ApplicationContext applicationContext,
                                         final AnnotationScanMetadataReaderFactory metadataReaderFactory) {

jmix-localized-string-datatype/src/main/java/com/glebfox/jmix/locstr/LocstrProperties.java

@@ -24,72 +24,144 @@
 @ConfigurationProperties(prefix = LocstrProperties.PREFIX)
 public class LocstrProperties {
 
+    /**
+     * Root configuration prefix for the add-on.
+     */
     public static final String PREFIX = "jmix.locstr";
+
+    /**
+     * Configuration prefix for database-level sorting settings.
+     */
     public static final String SORTING_DATABASE_PREFIX = PREFIX + ".sorting.database";
+
+    /**
+     * Configuration prefix for in-memory sorting settings.
+     */
     public static final String SORTING_IN_MEMORY_PREFIX = PREFIX + ".sorting.in-memory";
 
     /**
      * Sorting customization settings.
      */
     private Sorting sorting = new Sorting();
 
+    /**
+     * Returns sorting customization settings.
+     *
+     * @return sorting settings
+     */
     public Sorting getSorting() {
         return sorting;
     }
 
+    /**
+     * Sets sorting customization settings.
+     *
+     * @param sorting sorting settings
+     */
     public void setSorting(Sorting sorting) {
         this.sorting = sorting;
     }
 
+    /**
+     * Groups sorting customization settings.
+     */
     public static class Sorting {
 
         private Database database = new Database();
         private InMemory inMemory = new InMemory();
 
+        /**
+         * Returns database-level sorting settings.
+         *
+         * @return database-level sorting settings
+         */
         public Database getDatabase() {
             return database;
         }
 
+        /**
+         * Sets database-level sorting settings.
+         *
+         * @param database database-level sorting settings
+         */
         public void setDatabase(Database database) {
             this.database = database;
         }
 
+        /**
+         * Returns in-memory sorting settings.
+         *
+         * @return in-memory sorting settings
+         */
         public InMemory getInMemory() {
             return inMemory;
         }
 
+        /**
+         * Sets in-memory sorting settings.
+         *
+         * @param inMemory in-memory sorting settings
+         */
         public void setInMemory(InMemory inMemory) {
             this.inMemory = inMemory;
         }
     }
 
+    /**
+     * Configures database-level sorting for localized string attributes.
+     */
     public static class Database {
 
         /**
          * Whether to register the add-on database-level sorting customization for LocalizedString attributes.
          */
         private boolean enabled = true;
 
+        /**
+         * Returns whether database-level sorting customization is enabled.
+         *
+         * @return {@code true} if database-level sorting customization is
+         * enabled
+         */
         public boolean isEnabled() {
             return enabled;
         }
 
+        /**
+         * Sets whether database-level sorting customization is enabled.
+         *
+         * @param enabled {@code true} to enable database-level sorting
+         *                customization
+         */
         public void setEnabled(boolean enabled) {
             this.enabled = enabled;
         }
     }
 
+    /**
+     * Configures in-memory sorting for localized string attributes.
+     */
     public static class InMemory {
 
         /**
          * Whether to register the add-on in-memory sorting customization for LocalizedString attributes.
          */
         private boolean enabled = true;
 
+        /**
+         * Returns whether in-memory sorting customization is enabled.
+         *
+         * @return {@code true} if in-memory sorting customization is enabled
+         */
         public boolean isEnabled() {
             return enabled;
         }
 
+        /**
+         * Sets whether in-memory sorting customization is enabled.
+         *
+         * @param enabled {@code true} to enable in-memory sorting customization
+         */
         public void setEnabled(boolean enabled) {
             this.enabled = enabled;
         }