Add comments describing public methods

Author: pujagani

src/main/java/io/appium/java_client/proxy/ElementAwareWebDriverListener.java

@@ -34,13 +34,36 @@
 public class ElementAwareWebDriverListener implements MethodCallListener, ProxyAwareListener {
     private WebDriver parent;
 
+    /**
+     * Attaches the WebDriver proxy instance to this listener.
+     * <p>
+     * The listener stores the WebDriver instance to associate it as parent to RemoteWebElement proxies.
+     *
+     * @param proxy A proxy instance of {@link WebDriver}.
+     */
     @Override
     public void attachProxyInstance(Object proxy) {
         if (proxy instanceof WebDriver) {
             this.parent = (WebDriver) proxy;
         }
     }
 
+    /**
+     * Intercepts method calls on a proxied WebDriver.
+     * <p>
+     * If the result of the method call is a {@link RemoteWebElement},
+     * it is wrapped with a proxy to allow further interception of RemoteWebElement method calls.
+     * If the result is a list, each item is checked, and all RemoteWebElements are
+     * individually proxied. All other return types are passed through unmodified.
+     * Avoid overriding this method, it will alter the behaviour of the listener.
+     *
+     * @param obj      The object on which the method was invoked.
+     * @param method   The method being invoked.
+     * @param args     The arguments passed to the method.
+     * @param original A {@link Callable} that represents the original method execution.
+     * @return The (possibly wrapped) result of the method call.
+     * @throws Throwable if the original method or any wrapping logic throws an exception.
+     */
     @Override
     public Object call(Object obj, Method method, Object[] args, Callable<?> original) throws Throwable {
         Object result = original.call();

src/main/java/io/appium/java_client/proxy/ProxyAwareListener.java

@@ -16,7 +16,26 @@
 
 package io.appium.java_client.proxy;
 
+/**
+ * Extension of {@link MethodCallListener} that allows access to the proxy instance it depends on.
+ * <p>
+ * This interface is intended for listeners that need a reference to the proxy object.
+ * <p>
+ * The {@link #attachProxyInstance(Object)} method will be invoked immediately after the proxy is created,
+ * allowing the listener to bind to it before any method interception begins.
+ * <p>
+ * Example usage: Working with elements such as
+ * {@code RemoteWebElement} that require runtime mutation (e.g. setting parent driver or element ID).
+ */
 public interface ProxyAwareListener extends MethodCallListener {
+
+    /**
+     * Binds the listener to the proxy instance passed.
+     * <p>
+     * This is called once, immediately after proxy creation and before the proxy is returned to the caller.
+     *
+     * @param proxy the proxy instance created via {@code createProxy} that this listener is attached to.
+     */
     void attachProxyInstance(Object proxy);
 }