DOC: Small documentation changes and reorderd messages.

proto/caosdb/acm/v1alpha1/main.proto

@@ -26,7 +26,7 @@ option java_package        = "org.caosdb.api.acm.v1alpha1";
 package caosdb.acm.v1alpha1;
 
 ///////////////////////////////////////////
-// COMMON STUFF
+// COMMON MESSAGES
 ///////////////////////////////////////////
 
 // Client preferences for the paging. The server MUST respect the index
@@ -49,7 +49,7 @@ message PagingResponse {
 }
 
 ///////////////////////////////////////////
-// PERMISSSION STUFF
+// PERMISSSIONS
 ///////////////////////////////////////////
 
 // TODO
@@ -74,7 +74,7 @@ message PermissionDescription {
 message PermissionRule {
   // The permission which is being granted oder denied.
   string permission = 1;
-  // Priority permission rules overrule non-priority permission rules.
+  // Priority permission rules (TRUE) overrule non-priority (FALSE) permission rules.
   bool priority = 2;
   // True means that the permission is being granted by this rule, false means the
   // permission is being DENIED!
@@ -82,7 +82,7 @@ message PermissionRule {
 }
 
 ///////////////////////////////////////////
-// ROLE STUFF
+// ROLES
 ///////////////////////////////////////////
 
 // Role
@@ -114,9 +114,9 @@ message ListRolesResponse {
 message ListRoleItem {
   // Role
   Role role = 1;
-  // The permissions of the user of the current session
+  // The permissions of the user of the current session w.r.t. this role.
   repeated RolePermissions permissions = 2;
-  // What we can do with this role
+  // What can be done with this role.
   repeated RoleCapabilities capabilities = 3;
 }
 
@@ -135,41 +135,15 @@ message RetrieveSingleRoleRequest {
   string name = 1;
 }
 
-// Role Permissions
-enum RolePermissions {
-  // Unspecified permission
-  ROLE_PERMISSIONS_UNSPECIFIED = 0;
-  // Role can be deleted
-  ROLE_PERMISSIONS_DELETE = 1;
-  // Description can be updated
-  ROLE_PERMISSIONS_UPDATE_DESCRIPTION = 2;
-  // Permission rules of this role can be updated
-  ROLE_PERMISSIONS_UPDATE_PERMISSION_RULES = 3;
-  // This role can be assigned
-  ROLE_PERMISSIONS_ASSIGN = 4;
-}
-
-// Role Capabilities
-enum RoleCapabilities {
-  // Unspecified capability
-  ROLE_CAPABILITIES_UNSPECIFIED = 0;
-  // This role is deletable
-  ROLE_CAPABILITIES_DELETE = 1;
-  // This role's permissions can be changed
-  ROLE_CAPABILITIES_UPDATE_PERMISSION_RULES = 2;
-  // This role can be assigned to a user
-  ROLE_CAPABILITIES_ASSIGN = 3;
-}
-
 // Response message for the RetrieveSingleRole RPC
 message RetrieveSingleRoleResponse {
   // The role.
   Role role = 1;
   // Known users with this role
   repeated User users = 2;
-  // The permissions of the user of the current session
+  // The permissions of the user of the current session w.r.t. this role.
   repeated RolePermissions permissions = 3;
-  // What we can do with this role
+  // What can be do with this role.
   repeated RoleCapabilities capabilities = 4;
 }
 
@@ -190,8 +164,35 @@ message DeleteSingleRoleRequest {
 // Response message for the DeleteSingleRole RPC
 message DeleteSingleRoleResponse {}
 
+// Role Permissions
+enum RolePermissions {
+  // Unspecified permission
+  ROLE_PERMISSIONS_UNSPECIFIED = 0;
+  // Role can be deleted
+  ROLE_PERMISSIONS_DELETE = 1;
+  // Description can be updated
+  ROLE_PERMISSIONS_UPDATE_DESCRIPTION = 2;
+  // Permission rules of this role can be updated
+  ROLE_PERMISSIONS_UPDATE_PERMISSION_RULES = 3;
+  // This role can be assigned
+  ROLE_PERMISSIONS_ASSIGN = 4;
+}
+
+// Role Capabilities
+enum RoleCapabilities {
+  // Unspecified capability
+  ROLE_CAPABILITIES_UNSPECIFIED = 0;
+  // This role is deletable
+  ROLE_CAPABILITIES_DELETE = 1;
+  // This role's permissions can be changed
+  ROLE_CAPABILITIES_UPDATE_PERMISSION_RULES = 2;
+  // This role can be assigned to a user
+  ROLE_CAPABILITIES_ASSIGN = 3;
+}
+
+
 ///////////////////////////////////////////
-// USER STUFF
+// USERS
 ///////////////////////////////////////////
 
 // UserStatus
@@ -229,7 +230,7 @@ message User {
   UserStatus status = 1;
   // Realm of this user. The realm is the authority which can authenticate this
   // user, e.g. 'PAM' when the user is a (POSIX) user from the server's host, or
-  // 'CaosDB' when CaosDB Server itself can authenticate the user.
+  // 'CaosDB' when CaosDB server itself can authenticate the user.
   string realm = 2;
   // Name of this user.
   string name = 3;
@@ -264,7 +265,7 @@ message CreateSingleUserRequest {
   PasswordSetting password_setting = 2;
 }
 
-// Response message for the CreateSingeUser RPC
+// Response message for the CreateSingleUser RPC
 message CreateSingleUserResponse {}
 
 // Request message for the RetrieveSingleUser RPC
@@ -275,41 +276,13 @@ message RetrieveSingleUserRequest {
   string name = 2;
 }
 
-// Permissions for updating and deleting a user.
-enum UserPermissions {
-  // Unspecified permission
-  USER_PERMISSIONS_UNSPECIFIED = 0;
-  // The user can be deleted.
-  USER_PERMISSIONS_DELETE = 1;
-  // The password of the user can be updated.
-  USER_PERMISSIONS_UPDATE_PASSWORD = 2;
-  // The email of the user can be updated.
-  USER_PERMISSIONS_UPDATE_EMAIL = 3;
-  // The status (active/inactive) of the user can be changed.
-  USER_PERMISSIONS_UPDATE_STATUS = 4;
-  // The roles of the user can be altered.
-  USER_PERMISSIONS_UPDATE_ROLES = 5;
-  // Ths entity of the user can be set.
-  USER_PERMISSIONS_UPDATE_ENTITY = 6;
-}
-
-// What we can do with a user (generally speaking, if permissions suffice).
-enum UserCapabilities {
-  // Unspecified capability
-  USER_CAPABILITIES_UNSPECIFIED = 0;
-  // User can be deleted.
-  USER_CAPABILITIES_DELETE = 1;
-  // The user's password can be updated.
-  USER_CAPABILITIES_UPDATE_PASSWORD = 2;
-}
-
 // Response message for the RetrieveSingleUser RPC
 message RetrieveSingleUserResponse {
   // The user
   User user = 1;
   // The permissions of the user of the current session.
   repeated UserPermissions permissions = 2;
-  // What we can do with this user
+  // What can be done with this user
   repeated UserCapabilities capabilities = 3;
 }
 
@@ -335,6 +308,35 @@ message DeleteSingleUserRequest {
 // Response message for the DeleteSingleUser RPC
 message DeleteSingleUserResponse {}
 
+// Permissions for updating and deleting a user.
+enum UserPermissions {
+  // Unspecified permission
+  USER_PERMISSIONS_UNSPECIFIED = 0;
+  // The user can be deleted.
+  USER_PERMISSIONS_DELETE = 1;
+  // The password of the user can be updated.
+  USER_PERMISSIONS_UPDATE_PASSWORD = 2;
+  // The email of the user can be updated.
+  USER_PERMISSIONS_UPDATE_EMAIL = 3;
+  // The status (active/inactive) of the user can be changed.
+  USER_PERMISSIONS_UPDATE_STATUS = 4;
+  // The roles of the user can be altered.
+  USER_PERMISSIONS_UPDATE_ROLES = 5;
+  // Ths entity of the user can be set.
+  USER_PERMISSIONS_UPDATE_ENTITY = 6;
+}
+
+// What can be done with a user (generally speaking, if permissions suffice).
+enum UserCapabilities {
+  // Unspecified capability
+  USER_CAPABILITIES_UNSPECIFIED = 0;
+  // User can be deleted.
+  USER_CAPABILITIES_DELETE = 1;
+  // The user's password can be updated.
+  USER_CAPABILITIES_UPDATE_PASSWORD = 2;
+}
+
+
 ///////////////////////////////////////////
 // SERVICE DEFINITION
 ///////////////////////////////////////////