Add javadoc documentation for the newly added methods

JPro-one · Nov 19, 2024 · 785cbca · 785cbca
1 parent 7ff18d4
commit 785cbca
Showing 1 changed file with 41 additions and 8 deletions.
diff --git a/jpro-file/src/main/java/one/jpro/platform/file/picker/BaseFilePicker.java b/jpro-file/src/main/java/one/jpro/platform/file/picker/BaseFilePicker.java
@@ -86,6 +86,13 @@ public final ObjectProperty<ExtensionFilter> selectedExtensionFilterProperty() {
         return selectedExtensionFilter;
     }
 
+    /**
+     * Finds and returns the currently selected {@link ExtensionFilter}. If no filter is selected
+     * or the selected filter is not present in the list, the first filter in the list is returned.
+     * If the list is empty, {@code null} is returned.
+     *
+     * @return the selected extension filter or a default filter, or {@code null} if no filters are available
+     */
     final ExtensionFilter findSelectedFilter() {
         ExtensionFilter selectedFilter = getSelectedExtensionFilter();
         if (selectedFilter == null || !extensionFilters.contains(selectedFilter)) {
@@ -95,13 +102,26 @@ final ExtensionFilter findSelectedFilter() {
         }
     }
 
+    /**
+     * Synchronizes the selected {@link ExtensionFilter} between this file picker and the native {@link FileChooser}.
+     * This ensures that changes in one are reflected in the other without causing infinite update loops.
+     *
+     * @param fileChooser the native file chooser to synchronize with; must not be {@code null}
+     */
     final void synchronizeSelectedExtensionFilter(FileChooser fileChooser) {
         fileChooser.selectedExtensionFilterProperty()
                 .addListener(new WeakChangeListener<>(getNativeSelectedExtensionFilterChangeListener()));
         selectedExtensionFilterProperty()
                 .addListener(new WeakChangeListener<>(getSelectedExtensionFilterChangeListener(fileChooser)));
     }
 
+    /**
+     * Creates a {@link ChangeListener} that listens for changes in the native {@link FileChooser}'s
+     * selected extension filter and updates the corresponding property in this file picker.
+     *
+     * @return a change listener for the native file chooser's selected extension filter
+     */
+    @NotNull
     private ChangeListener<FileChooser.ExtensionFilter> getNativeSelectedExtensionFilterChangeListener() {
         return (observable, oldFilter, newFilter) -> {
             if (updatingFromProperty) {
@@ -125,6 +145,13 @@ private ChangeListener<FileChooser.ExtensionFilter> getNativeSelectedExtensionFi
         };
     }
 
+    /**
+     * Creates a {@link ChangeListener} that listens for changes in the native {@link FileChooser}'s
+     * selected extension filter and updates the corresponding property in this file picker.
+     *
+     * @return a change listener for the native file chooser's selected extension filter
+     */
+    @NotNull
     private ChangeListener<ExtensionFilter> getSelectedExtensionFilterChangeListener(FileChooser fileChooser) {
         return (observable, oldFilter, newFilter) -> {
             if (updatingFromFileChooser) {
@@ -150,11 +177,14 @@ private ChangeListener<ExtensionFilter> getSelectedExtensionFilterChangeListener
     }
 
     /**
-     * Creates a listener for changes in the list of extension filters for a native file chooser.
-     * When extension filters are added or removed, the file chooser's extension filters are updated accordingly.
+     * Creates a {@link ListChangeListener} that listens for changes in the list of {@link ExtensionFilter}
+     * instances and updates the native {@link FileChooser}'s extension filters accordingly.
+     * <p>
+     * This listener handles both additions and removals of extension filters.
+     * </p>
      *
-     * @param fileChooser the native file chooser whose extension filters will be updated
-     * @return A ListChangeListener that updates the extension filters of the native file chooser.
+     * @param fileChooser the native file chooser whose extension filters will be updated; must not be {@code null}
+     * @return a list change listener for updating the native file chooser's extension filters
      */
     @NotNull
     final ListChangeListener<ExtensionFilter> getNativeExtensionFilterListChangeListener(FileChooser fileChooser) {
@@ -175,11 +205,14 @@ final ListChangeListener<ExtensionFilter> getNativeExtensionFilterListChangeList
     }
 
     /**
-     * Creates a listener for changes in the list of extension filters for a web file uploader.
-     * When extension filters are added or removed, the web file uploader's supported extensions are updated accordingly.
+     * Creates a {@link ListChangeListener} that listens for changes in the list of {@link ExtensionFilter}
+     * instances and updates the web-based file uploader's supported extensions accordingly.
+     * <p>
+     * This listener handles both additions and removals of extension filters.
+     * </p>
      *
-     * @param multiFileUploader the web file uploader whose supported extensions will be updated
-     * @return A ListChangeListener that updates the supported extensions of the web file uploader.
+     * @param multiFileUploader the web file uploader whose supported extensions will be updated; must not be {@code null}
+     * @return a list change listener for updating the web file uploader's supported extensions
      */
     @NotNull
     final ListChangeListener<ExtensionFilter> getWebExtensionFilterListChangeListener(WebAPI.MultiFileUploader multiFileUploader) {