From a7280d29434beb31ae86490fd510878ddcf414a0 Mon Sep 17 00:00:00 2001
From: James Lu <GLolol@overdrivenetworks.com>
Date: Fri, 24 Feb 2017 18:28:28 -0800
Subject: [PATCH] docs/t: more notes regarding the permissions API

---
 docs/technical/permissions-api.md | 10 +++++++++-
 docs/technical/writing-plugins.md |  4 ++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/technical/permissions-api.md b/docs/technical/permissions-api.md
index 8c1548e..ea0d4c2 100644
--- a/docs/technical/permissions-api.md
+++ b/docs/technical/permissions-api.md
@@ -1,13 +1,21 @@
 # The Permissions API
 
-Permissions were introduced in PyLink 1.0 as a better (but optional) way for plugins to manage access to commands. The permissions system in PyLink is fairly simple, globally assigning a list of permissions to each hostmask/exttarget.
+Permissions were introduced in PyLink 1.0 as a way for plugins to manage command access, replacing the old `irc.checkAuthenticated()`. The permissions system in PyLink is fairly simple, globally assigning a list of permissions to each hostmask/exttarget.
 
 Permissions take the format `pluginname.commandname.optional_extra_portion(s)`, and support wildcards in matching. Permission nodes are case-insensitive and casemapping aware, but are conventionally defined as being all lowercase.
 
+The permissions module is available as `pylinkirc.coremods.permissions`. Usually, plugins import it this format:
+
+```python
+from pylinkirc.coremods import permissions
+```
+
 ## Checking for permissions
 
 Individual functions check for permissions using the `permissions.checkPermissions(irc, source, ['perm.1', 'perm.2'])` function, where the last argument is an OR'ed list of permissions (i.e. users only need one out of all of them). This function returns `True` when a permission check passes, and raises `utils.NotAuthorizedError` when a check fails, automatically aborting the execution of the command function.
 
+`utils.NotAuthorizedError` can be treated like any other exception, so it's possible to wrap it around `try:` / `except:` for more complex access checking ([example in the Automode plugin](https://github.com/GLolol/PyLink/blob/1.1.1/plugins/automode.py#L64-L68)).
+
 ## Assigning default permissions
 
 Plugins are also allowed to assign default permissions to their commands, though this should be used sparingly to ensure maximum configurability (explicitly removing permissions isn't supported yet). Default permissions are specified as a `dict` mapping targets to permission lists.
diff --git a/docs/technical/writing-plugins.md b/docs/technical/writing-plugins.md
index 0703f48..b9b000b 100644
--- a/docs/technical/writing-plugins.md
+++ b/docs/technical/writing-plugins.md
@@ -59,6 +59,10 @@ are preferred.
 
 The sender UID for both can be set using the `source` argument, and defaults to the main PyLink client.
 
+## Access checking for commands
+
+See the [Permissions API documentation](permissions-api.md) on how to restrict commands to certain users.
+
 ## Special triggers for plugin (un)loading
 
 The following functions can also be defined in the body of a plugin to hook onto plugin loading / unloading.