# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1642964132 -3600
# Node ID 3edf1a38fb15232dd35799750f6ff572beb0d2a9
# Parent  65e252940337f55aa5489b2a24e82e16561f4d06
mod_admin_shell: Add help section about roles

As in the argument to user:create() and user:roles()

Tricky to come up with something sensible to write when Prosody core
only knows of the 'prosody:admin' role so far.

diff -r 65e252940337 -r 3edf1a38fb15 plugins/mod_admin_shell.lua
--- a/plugins/mod_admin_shell.lua	Fri Jan 21 18:42:38 2022 +0100
+++ b/plugins/mod_admin_shell.lua	Sun Jan 23 19:55:32 2022 +0100
@@ -216,6 +216,7 @@
 		print [[module - Commands to load/reload/unload modules/plugins]]
 		print [[host - Commands to activate, deactivate and list virtual hosts]]
 		print [[user - Commands to create and delete users, and change their passwords]]
+		print [[roles - Show information about user roles]]
 		print [[muc - Commands to create, list and manage chat rooms]]
 		print [[server - Uptime, version, shutting down, etc.]]
 		print [[port - Commands to manage ports the server is listening on]]
@@ -253,6 +254,17 @@
 		print [[user:roles(jid, host, roles) - Set roles for an user (see 'help roles')]]
 		print [[user:delete(jid) - Permanently remove the specified user account]]
 		print [[user:list(hostname, pattern) - List users on the specified host, optionally filtering with a pattern]]
+	elseif section == "roles" then
+		print [[Roles may grant access or restrict users from certain operations]]
+		print [[Built-in roles are:]]
+		print [[  prosody:admin - Administrator]]
+		print [[  (empty set) - Normal user]]
+		print [[]]
+		print [[The canonical role format looks like: { ["example:role"] = true }]]
+		print [[For convenience, the following formats are also accepted:]]
+		print [["admin" - short for "prosody:admin", the normal admin status (like the admins config option)]]
+		print [["example:role" - short for {["example:role"]=true}]]
+		print [[{"example:role"} - short for {["example:role"]=true}]]
 	elseif section == "muc" then
 		-- TODO `muc:room():foo()` commands
 		print [[muc:create(roomjid, { config }) - Create the specified MUC room with the given config]]