Added javadocs for PrincipalMapper

Author: artem-v

services-api/src/main/java/io/scalecube/services/auth/Principal.java

@@ -9,8 +9,8 @@
 public interface Principal {
 
   /**
-   * A constant representing a "null" principal, which signifies an unauthenticated entity. This
-   * principal does not have any roles or permissions.
+   * Null principal, which signifies an unauthenticated entity. This principal does not have any
+   * roles or permissions.
    */
   Principal NULL_PRINCIPAL =
       new Principal() {

services-api/src/main/java/io/scalecube/services/auth/PrincipalMapper.java

@@ -3,8 +3,23 @@
 import io.scalecube.services.RequestContext;
 import reactor.core.publisher.Mono;
 
+/**
+ * Functional interface for transforming existing {@link Principal} from {@link RequestContext} to
+ * the new {@link Principal}. This interface allows to modify or replace a current principal from
+ * {@link RequestContext}, allowing for dynamic adjustments to authentication and authorization
+ * logic based on the request context.
+ *
+ * @see Principal
+ * @see RequestContext
+ */
 @FunctionalInterface
 public interface PrincipalMapper {
 
+  /**
+   * Maps current principal in the provided {@link RequestContext} to the new {@link Principal}.
+   *
+   * @param requestContext {@link RequestContext} containing the current principal
+   * @return {@link Mono} emitting the new {@link Principal} after the transformation
+   */
   Mono<Principal> map(RequestContext requestContext);
 }