Merge branch 'f-acm-docchanges' into 'f-acm'

F acm docchanges

See merge request !6

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,12 +49,11 @@ message PagingResponse {
 }
 
 ///////////////////////////////////////////
-// PERMISSSION STUFF
+// PERMISSSIONS
 ///////////////////////////////////////////
 
 // TODO
-message ListKnownPermissionsRequest {
-}
+message ListKnownPermissionsRequest {}
 
 // TODO
 message ListKnownPermissionsResponse {
@@ -74,15 +73,16 @@ 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!
+  // True means that the permission is being granted by this rule, false means
+  // the permission is being DENIED!
   bool grant = 3;
 }
 
 ///////////////////////////////////////////
-// 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,34 @@ 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
@@ -204,19 +204,23 @@ enum UserStatus {
   USER_STATUS_ACTIVE = 2;
 }
 
-// PasswordSetting - it is handy to have this as a separate message b/c otherwise we could not distinguish between empty string and an unspecified password.
+// PasswordSetting - it is handy to have this as a separate message b/c
+// otherwise we could not distinguish between empty string and an unspecified
+// password.
 message PasswordSetting {
   // The password
   string password = 1;
 }
 
-// EmailSetting - it is handy to have this as a separate message b/c otherwise we could not distinguish between empty string and an unspecified email.
+// EmailSetting - it is handy to have this as a separate message b/c otherwise
+// we could not distinguish between empty string and an unspecified email.
 message EmailSetting {
   // The email adress
   string email = 1;
 }
 
-// EntitySetting - it is handy to have this as a separate message b/c otherwise we could not distinguish between empty string and an unspecified entity.
+// EntitySetting - it is handy to have this as a separate message b/c otherwise
+// we could not distinguish between empty string and an unspecified entity.
 message EntitySetting {
   // The entity which represents this user (e.g. a Person or Device Record).
   string entity_id = 1;
@@ -229,7 +233,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 +268,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 +279,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 +311,34 @@ 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
 ///////////////////////////////////////////

proto/caosdb/entity/v1/main.proto

@@ -710,8 +710,7 @@ message MultiUpdateEntityACLRequest {
 }
 
 // Response of the MultiUpdateEntityACL rpc
-message MultiUpdateEntityACLResponse {
-}
+message MultiUpdateEntityACLResponse {}
 
 // Entity Access Controll List (ACL)
 message EntityACL {
@@ -739,7 +738,10 @@ message EntityPermissionRule {
   repeated EntityPermissionRuleCapability capabilities = 5;
 }
 
-// What (given enough permissions) can be done with an EntityPermissionRule. E.g. globel entity permission rules, which are to be specified in a configuration file cannot be deleted, thus they are missing the ENTITY_PERMISSION_RULE_CAPABILITY_DELETE capability.
+// What (given enough permissions) can be done with an EntityPermissionRule.
+// E.g. globel entity permission rules, which are to be specified in a
+// configuration file cannot be deleted, thus they are missing the
+// ENTITY_PERMISSION_RULE_CAPABILITY_DELETE capability.
 enum EntityPermissionRuleCapability {
   // Unspecified capability.
   ENTITY_PERMISSION_RULE_CAPABILITY_UNSPECIFIED = 0;