Rewrite kiosk documentation

A lot of kiosk stuff is actually in other frameworks, from the point of
view of applications, but KConfig provides the core functionality.  Make
the docs here describe KConfig's role, rather than KIO's or KXMLGui's.

REVIEW: 117486

2 files changed, 89 insertions, 20 deletions

diff --git a/src/core/kauthorized.cpp b/src/core/kauthorized.cpp
index c9b14f50..4280524d 100644
--- a/src/core/kauthorized.cpp
+++ b/src/core/kauthorized.cpp
@@ -340,7 +340,10 @@ static void initUrlActionRestrictions()
 
 namespace KAuthorized
 {
-// Called by KAuthorized::allowUrlAction in KIO
+/**
+ * Helper for KAuthorized::allowUrlAction in KIO
+ * @private
+ */
 KCONFIGCORE_EXPORT void allowUrlActionInternal(const QString &action, const QUrl &_baseURL, const QUrl &_destURL)
 {
     MY_D
@@ -359,7 +362,10 @@ KCONFIGCORE_EXPORT void allowUrlActionInternal(const QString &action, const QUrl
                                      _destURL.scheme(), _destURL.host(), destPath, true));
 }
 
-// Called by KAuthorized::authorizeUrlAction in KIO
+/**
+ * Helper for KAuthorized::authorizeUrlAction in KIO
+ * @private
+ */
 KCONFIGCORE_EXPORT bool authorizeUrlActionInternal(const QString &action, const QUrl &_baseURL, const QUrl &_destURL, const QString &baseClass, const QString &destClass)
 {
     MY_D
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);