Doc updates

2 files changed, 10 insertions, 3 deletions

diff --git a/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Policy.java b/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Policy.java
index 6f1ce77f5cd..85702ac1b89 100644
--- a/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Policy.java
+++ b/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Policy.java
@@ -1,12 +1,17 @@
 // Copyright 2019 Oath Inc. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
 package com.yahoo.vespa.hosted.controller.role;
 
+import com.yahoo.config.provision.ApplicationName;
 import com.yahoo.config.provision.SystemName;
+import com.yahoo.config.provision.TenantName;
 
 import java.util.Set;
 
 /**
  * Policies for REST APIs in the controller. A policy is only considered when defined in a {@link Role}.
+ * A policy describes a set of {@link Privilege}s, which are valid for a set of {@link SystemName}s.
+ * A policy is evaluated with a {@link Context}, which provides the {@link SystemName} the policy is
+ * evaluated in, and any limitations to a specific {@link TenantName} or {@link ApplicationName}.
  *
  * @author mpolden
  */
diff --git a/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Role.java b/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Role.java
index a195c1924fe..cae143a92a2 100644
--- a/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Role.java
+++ b/controller-server/src/main/java/com/yahoo/vespa/hosted/controller/role/Role.java
@@ -5,9 +5,11 @@ import java.util.EnumSet;
 import java.util.Set;
 
 /**
- * This declares all tenant roles known to the controller. A role contains one or more {@link Policy}'s which decide
- * what actions a member of a role can perform, and, optionally, a "lower ranking" role from which all policies are
- * inherited. Read the list of roles from everyone to tenantAdmin, in order, to see what policies such a role includes.
+ * This declares all tenant roles known to the controller. A role contains one or more {@link Policy}s which decide
+ * what actions a member of a role can perform.
+ *
+ * Optionally, some role definition also inherit all policies from a "lower ranking" role. Read the list of roles
+ * from {@code everyone} to {@code tenantAdmin}, in order, to see what policies these roles.
  *
  * @author mpolden
  * @author jonmv