user-list.h: Improve documentation of permission flags.

The documentation of the server_command_permissions enum is a bit
sparse, and doxygen complains about it because the members of the
enumeration are not documented.

The new documentation of the permission flags avoids to talk about
commands because the flags are not only about commands but also about
the per-user permission settings.

diff --git a/user_list.h b/user_list.h
index f4e7661b5eb7900d43afa4ee4cd26c7771267a11..3a77e98fa8c4636406035ce66f7842235832db4d 100644 (file)
--- a/user_list.h
+++ b/user_list.h
@@ -7,14 +7,19 @@
 /** \file user_list.h exported functions from user_list.c */
 
 /**
- * permission flags that can be set individually for any server command
+ * Flags for server commands and user permissions.
  *
- * - AFS_READ: read-only command of the audio file selector
- * - AFS_WRITE: command changes state of the audio file selector
- * - VSS_READ: command reads information about the current audio stream
- * - VSS_WRITE: command changes the current audio stream
+ * For each command, zero or more of these flags are ored to define the command
+ * permissions. A user is allowed to run the command if and only if all command
+ * permission flags are set for the user in the server.users config file which
+ * is read at server startup.
  */
-enum {AFS_READ = 1, AFS_WRITE = 2, VSS_READ = 4, VSS_WRITE = 8};
+enum server_command_permissions {
+       AFS_READ = 1, /** Read-only operation on the AFS database. */
+       AFS_WRITE = 2, /** Read-write operation on the AFS database. */
+       VSS_READ = 4, /** Read-only operation on the virtual streaming system. */
+       VSS_WRITE = 8 /** Read-write operation on the virtual streaming system. */
+};
 
 /**
  * data needed to authenticate the user