Add additional comments to the experimental reflection APIs

Author: josephschorr

authzed/api/v1/experimental_service.proto

@@ -207,6 +207,7 @@ message ExperimentalReflectSchemaResponse {
   ZedToken read_at = 3;
 }
 
+// ExpSchemaFilter is a filter that can be applied to the schema on reflection.
 message ExpSchemaFilter {
   // optional_definition_name_match is a regex that is matched against the definition name.
   string optional_definition_name_match = 1;
@@ -221,35 +222,49 @@ message ExpSchemaFilter {
   string optional_permission_name_match = 4;
 }
 
+// ExpDefinition is the representation of a definition in the schema.
 message ExpDefinition {
   string name = 1;
+
+  // comment is a human-readable comments on the definition. Will include
+  // delimiter characters.
   string comment = 2;
 
   repeated ExpRelation relations = 3;
   repeated ExpPermission permissions = 4;
 }
 
+// ExpCaveat is the representation of a caveat in the schema.
 message ExpCaveat {
   string name = 1;
+
+  // comment is a human-readable comments on the caveat. Will include
+  // delimiter characters.
   string comment = 2;
 
   repeated ExpCaveatParameter parameters = 3;
   string expression = 4;
 }
 
+// ExpCaveatParameter is the representation of a parameter in a caveat.
 message ExpCaveatParameter {
   string name = 1;
+
+  // type is the type of the parameter. Will be a string representing the
+  // type, e.g. `int` or `list<string>`
   string type = 2;
   string parent_caveat_name = 3;
 }
 
+// ExpRelation is the representation of a relation in the schema.
 message ExpRelation {
   string name = 1;
   string comment = 2;
   string parent_definition_name = 3;
   repeated ExpTypeReference subject_types = 4;
 }
 
+// ExpTypeReference is the representation of a type reference in the schema.
 message ExpTypeReference {
   // subject_definition_name is the name of the subject's definition.
   string subject_definition_name = 1;
@@ -269,8 +284,12 @@ message ExpTypeReference {
   }
 }
 
+// ExpPermission is the representation of a permission in the schema.
 message ExpPermission {
   string name = 1;
+
+  // comment is a human-readable comments on the permission. Will include
+  // delimiter characters.
   string comment = 2;
   string parent_definition_name = 3;
 }
@@ -285,14 +304,16 @@ message ExperimentalComputablePermissionsRequest {
   string optional_definition_name_match = 3;
 }
 
+// ExpRelationReference is a reference to a relation in the schema.
 message ExpRelationReference {
   string definition_name = 1;
   string relation_name = 2;
 }
 
+// ExpPermissionReference is a reference to a permission in the schema.
 message ExpPermissionReference {
   string definition_name = 1;
-  string relation_name = 2;
+  string permission_name = 2;
 }
 
 message ExperimentalComputablePermissionsResponse {
@@ -336,6 +357,7 @@ message ExpCaveatParameterTypeChange {
   string previous_type = 2;
 }
 
+// ExpSchemaDiff is the representation of a diff between two schemas.
 message ExpSchemaDiff {
   oneof diff {
     ExpDefinition definition_added = 1;