diff --git a/modules/ppcp-settings/src/Endpoint/AuthenticationRestEndpoint.php b/modules/ppcp-settings/src/Endpoint/AuthenticationRestEndpoint.php
index f6310588e..037add444 100644
--- a/modules/ppcp-settings/src/Endpoint/AuthenticationRestEndpoint.php
+++ b/modules/ppcp-settings/src/Endpoint/AuthenticationRestEndpoint.php
@@ -23,7 +23,14 @@ use WooCommerce\PayPalCommerce\Settings\Data\GeneralSettings;
 use WooCommerce\PayPalCommerce\Settings\Service\ConnectionManager;
 
 /**
- * REST controller for connection to a PayPal merchant account.
+ * REST controller for authenticating and connecting to a PayPal merchant account.
+ *
+ * This endpoint is responsible for verifying credentials and establishing
+ * a connection, regardless of whether they are provided via:
+ * 1. Direct login (clientId + secret)
+ * 2. UI-driven login (sharedId + authCode)
+ *
+ * It handles the actual authentication process after the login URL has been used.
  */
 class AuthenticationRestEndpoint extends RestEndpoint {
 	/**
diff --git a/modules/ppcp-settings/src/Endpoint/LoginLinkRestEndpoint.php b/modules/ppcp-settings/src/Endpoint/LoginLinkRestEndpoint.php
index 8ed204383..9ce844f6d 100644
--- a/modules/ppcp-settings/src/Endpoint/LoginLinkRestEndpoint.php
+++ b/modules/ppcp-settings/src/Endpoint/LoginLinkRestEndpoint.php
@@ -15,7 +15,14 @@ use WP_REST_Request;
 use WooCommerce\PayPalCommerce\Settings\Service\ConnectionUrlGenerator;
 
 /**
- * REST controller that generates merchant login URLs.
+ * REST controller that generates merchant login URLs for PayPal.
+ *
+ * This endpoint is responsible solely for generating a URL that initiates
+ * the PayPal login flow. It does not handle the authentication itself.
+ *
+ * The generated URL is typically used to redirect merchants to PayPal's login page.
+ * After successful login, the authentication process is completed via the
+ * AuthenticationRestEndpoint.
  */
 class LoginLinkRestEndpoint extends RestEndpoint {
 	/**