diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/DefaultRepositorySystemSession.java b/maven-resolver-api/src/main/java/org/eclipse/aether/DefaultRepositorySystemSession.java
index 03507ceaf..3f46af54f 100644
--- a/maven-resolver-api/src/main/java/org/eclipse/aether/DefaultRepositorySystemSession.java
+++ b/maven-resolver-api/src/main/java/org/eclipse/aether/DefaultRepositorySystemSession.java
@@ -275,12 +275,19 @@ public String getUpdatePolicy() {
     /**
      * Sets the global update policy. If set, the global update policy overrides the update policies of the remote
      * repositories being used for resolution.
+     * <p>
+     * This method is meant for code that does not want to distinguish between artifact and metadata policies.
+     * Note: applications should either use get/set updatePolicy (this method and
+     * {@link RepositorySystemSession#getUpdatePolicy()}) or also distinguish between artifact and
+     * metadata update policies (and use other methods), but <em>should not mix the two!</em>
      *
      * @param updatePolicy The global update policy, may be {@code null}/empty to apply the per-repository policies.
      * @return This session for chaining, never {@code null}.
      * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
      * @see RepositoryPolicy#UPDATE_POLICY_DAILY
      * @see RepositoryPolicy#UPDATE_POLICY_NEVER
+     * @see #setArtifactUpdatePolicy(String)
+     * @see #setMetadataUpdatePolicy(String)
      */
     public DefaultRepositorySystemSession setUpdatePolicy(String updatePolicy) {
         verifyStateForMutation();
diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystemSession.java b/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystemSession.java
index 8bd4828f6..c101621ee 100644
--- a/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystemSession.java
+++ b/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystemSession.java
@@ -93,10 +93,15 @@ public interface RepositorySystemSession {
     String getChecksumPolicy();
 
     /**
-     * Method for code that does not want to distinguish between artifact and metadata policies, in reality this
-     * is method invokes {@link #getArtifactUpdatePolicy()}.
+     * Gets the global update policy, or {@code null} if not set.
+     * <p>
+     * This method is meant for code that does not want to distinguish between artifact and metadata policies.
+     * Note: applications should either use get/set updatePolicy (this method and
+     * {@link DefaultRepositorySystemSession#setUpdatePolicy(String)}) or also distinguish between artifact and
+     * metadata update policies (and use other methods), but <em>should not mix the two!</em>
      *
      * @see #getArtifactUpdatePolicy()
+     * @see #getMetadataUpdatePolicy()
      */
     String getUpdatePolicy();
 
diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/repository/RepositoryPolicy.java b/maven-resolver-api/src/main/java/org/eclipse/aether/repository/RepositoryPolicy.java
index 0c7781760..9692fe99b 100644
--- a/maven-resolver-api/src/main/java/org/eclipse/aether/repository/RepositoryPolicy.java
+++ b/maven-resolver-api/src/main/java/org/eclipse/aether/repository/RepositoryPolicy.java
@@ -110,11 +110,14 @@ public boolean isEnabled() {
     }
 
     /**
-     * Shorthand for {@link #getArtifactUpdatePolicy()}. This method is not used in Resolver, nor should be
-     * used outside it. Internally, resolver strictly distinguishes between artifact and metadata update
-     * policies.
+     * This method is not used in Resolver, as resolver internally strictly distinguishes between artifact and metadata
+     * update policies.
      *
-     * @deprecated Use {@link #getArtifactUpdatePolicy()} or {@link #getMetadataUpdatePolicy()} instead.
+     * @see #getArtifactUpdatePolicy()
+     * @see #getMetadataUpdatePolicy() 
+     * @deprecated This method should not be used. Since version 2 Resolver internally distinguishes between artifact
+     * update policy and metadata update policy. This method was left only to preserve binary compatibility, and in
+     * reality invokes {@link #getArtifactUpdatePolicy()}.
      */
     @Deprecated
     public String getUpdatePolicy() {