1 files changed, 81 insertions, 18 deletions
diff --git a/src/core/kauthorized.h b/src/core/kauthorized.h
index 45dd8284..d0988234 100644
--- a/src/core/kauthorized.h
+++ b/src/core/kauthorized.h
@@ -28,43 +28,106 @@ class QString;
 class QStringList;
 
 /**
-* Kiosk authorization framework
+* The functions in this namespace provide the core of the Kiosk action
+* restriction system; the KIO and KXMLGui frameworks build on this.
 *
-* Core functionality, see kauthorized.h for authorizeUrlAction.
+* The relevant settings are read from the application's KSharedConfig
+* instance, so actions can be disabled on a per-application or global
+* basis (by using the kdeglobals file).
 */
 namespace KAuthorized
 {
 /**
- * Returns whether a certain action is authorized
- * @param genericAction The name of a generic action
- * @return true if the action is authorized
- * @todo what are the generic actions?
+ * Returns whether the user is permitted to perform a certain action.
+ *
+ * All settings are read from the "[KDE Action Restrictions]" group.
+ * For example, if kdeglobals contains
+ * @verbatim
+   [KDE Action Restrictions][$i]
+   shell_access=false
+   @endverbatim
+ * then
+ * @code
+ * KAuthorized::authorize("shell_access");
+ * @endcode
+ * will return @c false.
+ *
+ * This method is intended for actions that do not necessarily have a
+ * one-to-one correspondence with a menu or toolbar item (ie: a KAction
+ * in a KXMLGui application).  "shell_access" is an example of such a
+ * "generic" action.
+ *
+ * The convention for actions like "File->New" is to prepend the action
+ * name with "action/", for example "action/file_new".  This is what
+ * authorizeKAction() does.
+ *
+ * @param action  The name of the action.
+ * @return        @c true if the action is authorized, @c false
+ *                otherwise.
+ *
+ * @see authorizeKAction()
  */
-KCONFIGCORE_EXPORT bool authorize(const QString &genericAction);
+KCONFIGCORE_EXPORT bool authorize(const QString &action);
 
 /**
- * Returns whether a certain KAction is authorized.
+ * Returns whether the user is permitted to perform a certain action.
+ *
+ * This behaves like authorize(), except that "action/" is prepended to
+ * @p action.  So if kdeglobals contains
+ * @verbatim
+   [KDE Action Restrictions][$i]
+   action/file_new=false
+   @endverbatim
+ * then
+ * @code
+ * KAuthorized::authorizeKAction("file_new");
+ * @endcode
+ * will return @c false.
  *
- * @param action The name of a KAction action. The name is prepended
- * with "action/" before being passed to authorize()
- * @return true if the KAction is authorized
+ * KXMLGui-based applications should not normally need to call this
+ * function, as KActionCollection will do it automatically.
+ *
+ * @param action  The name of a KAction action.
+ * @return        @c true if the KAction is authorized, @c false
+ *                otherwise.
+ *
+ * @see authorize()
  */
 KCONFIGCORE_EXPORT bool authorizeKAction(const QString &action);
 
 /**
- * Returns whether access to a certain control module is authorized.
+ * Returns whether the user is permitted to use a certain control
+ * module.
+ *
+ * All settings are read from the "[KDE Control Module Restrictions]"
+ * group.  For example, if kdeglobals contains
+ * @verbatim
+   [KDE Control Module Restrictions][$i]
+   desktop-settings.desktop=false
+   @endverbatim
+ * then
+ * @code
+ * KAuthorized::authorizeControlModule("desktop-settings.desktop");
+ * @endcode
+ * will return @c false.
  *
- * @param menuId identifying the control module, e.g. kde-mouse.desktop
- * @return true if access to the module is authorized, false otherwise.
+ * @param menuId  The desktop menu ID for the control module.
+ * @return        @c true if access to the module is authorized,
+ *                @c false otherwise.
+ *
+ * @see authorizeControlModules()
  */
 KCONFIGCORE_EXPORT bool authorizeControlModule(const QString &menuId);
 
 /**
- * Returns which control modules from a given list are authorized for access.
+ * Determines which control modules from a list the user is permitted to
+ * use.
+ *
+ * @param menuIds  A list of desktop menu IDs for control modules.
+ * @return         The entries in @p menuIds for which
+ *                 authorizeControlModule() returns @c true.
  *
- * @param menuIds list of menu-ids of control modules;
- * an example of a menu-id is kde-mouse.desktop.
- * @return Those control modules for which access has been authorized.
+ * @see authorizeControlModule()
  */
 KCONFIGCORE_EXPORT QStringList authorizeControlModules(const QStringList &menuIds);