refactor(view): enhance documentation and clarify method responsibilities

Author: marioserrano09

platform/core/viewers/src/main/java/tools/dynamia/viewers/View.java

@@ -20,58 +20,96 @@
 import java.io.Serializable;
 
 /**
- * Interface representing a view with a value and descriptor.
+ * Core abstraction for a UI view that holds a typed value and is driven by a {@link ViewDescriptor}.
  *
- * @param <T> the type of value managed by the view
+ * <p>A {@code View} is the runtime representation of a UI component built by a {@link ViewRenderer}.
+ * It is parameterized by the type {@code T} of the domain object (or value) it displays or edits.
+ * The structure and behaviour of the view are defined by its associated {@link ViewDescriptor}.</p>
+ *
+ * <p>Views can be nested: a view may have a parent view, allowing composite UI hierarchies to be
+ * constructed (e.g., a sub-form embedded inside a main form).</p>
+ *
+ * <p>Typical lifecycle:
+ * <ol>
+ *   <li>A {@link ViewDescriptor} is resolved by {@link ViewDescriptorFactory}.</li>
+ *   <li>A {@code View} instance is created by {@link ViewFactory} using a {@link ViewRenderer}.</li>
+ *   <li>A value is set via {@link #setValue(Object)}, causing the view to reflect the domain object.</li>
+ * </ol>
+ * </p>
+ *
+ * @param <T> the type of the domain object (value) managed by this view
+ * @see ViewDescriptor
+ * @see ViewFactory
+ * @see ViewRenderer
  */
 public interface View<T> extends Serializable {
 
     /**
-     * Gets the value of the view.
+     * Returns the current value held by this view.
      *
-     * @return the value
+     * @return the current value, or {@code null} if no value has been set
      */
     T getValue();
 
     /**
-     * Sets the value of the view.
+     * Sets the value to be displayed or edited by this view.
+     *
+     * <p>Implementations should update the visual state of the view to reflect the new value.</p>
      *
-     * @param value the new value
+     * @param value the new value; may be {@code null}
      */
     void setValue(T value);
 
     /**
-     * Sets the view descriptor.
+     * Assigns the {@link ViewDescriptor} that defines the structure and metadata of this view.
      *
-     * @param viewDescriptor the new view descriptor
+     * <p>This is typically called once during view construction by the {@link ViewFactory}.</p>
+     *
+     * @param viewDescriptor the descriptor to associate with this view; must not be {@code null}
      */
     void setViewDescriptor(ViewDescriptor viewDescriptor);
 
     /**
-     * Gets the view descriptor.
+     * Returns the {@link ViewDescriptor} that describes the structure and metadata of this view.
      *
-     * @return the view descriptor
+     * @return the view descriptor; may be {@code null} if not yet initialized
      */
     ViewDescriptor getViewDescriptor();
 
     /**
-     * Gets the parent view.
+     * Returns the parent view that contains this view, if any.
+     *
+     * <p>Used to navigate composite view hierarchies.</p>
      *
-     * @return the parent view
+     * @return the parent {@link View}, or {@code null} if this is a top-level view
      */
     View getParentView();
 
     /**
-     * Sets the parent view.
+     * Sets the parent view that contains this view.
      *
-     * @param view the new parent view
+     * @param view the parent {@link View}; may be {@code null} for top-level views
      */
     void setParentView(View view);
 
+    /**
+     * Sets an arbitrary source object associated with this view.
+     *
+     * <p>The source can represent the originating controller, component, or context object.
+     * The default implementation is a no-op; subclasses may override to store the value.</p>
+     *
+     * @param source the source object; may be {@code null}
+     */
     default void setSource(Object source) {
-
     }
 
+    /**
+     * Returns the source object previously set via {@link #setSource(Object)}.
+     *
+     * <p>The default implementation always returns {@code null}; subclasses may override.</p>
+     *
+     * @return the source object, or {@code null} if not set
+     */
     default Object getSource() {
         return null;
     }

platform/core/viewers/src/main/java/tools/dynamia/viewers/ViewAction.java

@@ -3,7 +3,21 @@
 import tools.dynamia.actions.AbstractAction;
 
 /**
- * Represents an action associated with a viewer
+ * Base class for actions that are contextually bound to a {@link View}.
+ *
+ * <p>A {@code ViewAction} extends {@link AbstractAction} to provide all standard action
+ * capabilities (id, label, icon, enabled/visible state, execution) in a viewer-aware context.
+ * Subclasses are typically registered with a view or a {@link ViewDescriptor} via
+ * {@link ViewDescriptor#getActions()} and rendered as toolbar buttons, menu items, or
+ * inline controls by the {@link ViewRenderer}.</p>
+ *
+ * <p>Because view actions inherit from {@link AbstractAction}, they participate in the same
+ * action lifecycle (enable/disable, show/hide, execute with an
+ * {@link tools.dynamia.actions.ActionEvent}) as any other framework action, but can also
+ * interact directly with the hosting view.</p>
+ *
+ * @see AbstractAction
+ * @see ViewDescriptor#getActions()
  */
 public abstract class ViewAction extends AbstractAction {
 }

platform/core/viewers/src/main/java/tools/dynamia/viewers/ViewCustomizer.java

@@ -20,16 +20,38 @@
 import java.io.Serializable;
 
 /**
- * Interface for customizing a view after it is created.
+ * Post-processing hook applied to a {@link View} immediately after it is constructed by a
+ * {@link ViewRenderer}.
  *
- * @param <T> the type of view to customize
+ * <p>A {@code ViewCustomizer} allows framework users to programmatically adjust a view's
+ * appearance or behaviour without subclassing the renderer. Typical uses include:
+ * <ul>
+ *   <li>Attaching event listeners to form components.</li>
+ *   <li>Applying dynamic styles or CSS classes.</li>
+ *   <li>Changing field visibility based on runtime conditions.</li>
+ *   <li>Injecting additional child components.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>The concrete customizer class is declared in the {@link ViewDescriptor} via
+ * {@link ViewDescriptor#getViewCustomizerClass()} and is instantiated by the framework
+ * after the view is fully built. Implementations must be serializable and have a
+ * public no-arg constructor.</p>
+ *
+ * @param <T> the concrete {@link View} subtype this customizer operates on
+ * @see ViewDescriptor#getViewCustomizerClass()
+ * @see ViewRenderer
  */
 public interface ViewCustomizer<T extends View> extends Serializable {
 
     /**
-     * Customizes the given view.
+     * Applies custom post-processing logic to the given view.
+     *
+     * <p>This method is called once per view construction, after the {@link ViewRenderer}
+     * has finished building all components. Modifications made here are reflected in the
+     * final UI presented to the user.</p>
      *
-     * @param view the view to customize
+     * @param view the fully constructed view to customize; never {@code null}
      */
     void customize(T view);
 }