From b376aba591a58b134b4bd5a9e1cabca4d39f05eb Mon Sep 17 00:00:00 2001
From: James Lu <GLolol@overdrivenetworks.com>
Date: Sat, 23 Jul 2016 20:56:22 -0700
Subject: [PATCH] docs/t: add Services API description

Closes #224.
---
 docs/technical/README.md       |  3 +-
 docs/technical/services-api.md | 61 ++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/technical/services-api.md

diff --git a/docs/technical/README.md b/docs/technical/README.md
index a051c33..b577d43 100644
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -18,7 +18,8 @@ PyLink is an a modular, plugin-based IRC services framework. It uses swappable p
 - [PyLink hooks reference](hooks-reference.md)
 - [Supported named channel modes](channel-modes.csv)
 - [Supported named user modes](user-modes.csv)
+- [Services bot API/Creating your own service bots](services-api.md)
 
 ### Future topics (not yet available)
 - [Writing tests for PyLink modules](writing-tests.md)
-- [Services bot API/Creating your own service bots](services-api.md)
+
diff --git a/docs/technical/services-api.md b/docs/technical/services-api.md
new file mode 100644
index 0000000..2648bd6
--- /dev/null
+++ b/docs/technical/services-api.md
@@ -0,0 +1,61 @@
+# PyLink Services Bot API
+
+Starting with PyLink 0.9.x, a services bot API was introduced to make writing custom services slightly easier. PyLink's Services API automatically connects service bots, and handles rejoin on kick/kill all by itself, meaning less code is needed per plugin to have functional service bots.
+
+## Creating new services
+
+Services can be created (registered) using code similar to the following in a plugin:
+
+```python
+
+from pylinkirc import utils, world
+
+# Description is optional (though recommended), and usually around a sentence or two.
+desc = "Optional description of servicenick, in sentence form."
+
+# First argument is the internal service name.
+# utils.registerService() returns a utils.ServiceBot instance, which can also be found
+# by calling world["myservice"].
+myservice = utils.registerService("myservice", desc=desc)
+```
+
+`utils.registerService()` passes its arguments directly to the `utils.ServiceBot` class constructor, which in turn supports the following options:
+
+- **`name`** - defines the service name (mandatory)
+- `default_help` - Determines whether the default HELP command should be used for the service. Defaults to True.
+- `default_list` - Determines whether the default LIST command should be used for the service. Defaults to True.
+- `nick`, `ident` - Sets the default nick and ident for the service bot. If not given, these simply default to the service name.
+- `manipulatable` - Determines whether the bot is marked manipulatable. Only manipulatable clients can be force joined, etc. using PyLink commands. Defaults to False.
+- `extra_channels` - Defines a dict mapping network names to a set of channels that the bot should autojoin on that network.
+- `desc` - Sets the command description of the service. This is shown in the default HELP command if enabled.
+
+### Getting the UID of a bot
+
+Should you want to get the UID of a service bot on a specific server, use `myservice.uids.get('irc.name')`
+
+### Setting channels to join
+
+All services bots wil automatically join the autojoin channels configured for a specific network, if any.
+
+However, plugins can modify the autojoin entries of a specific bot by adding items to the `myservice.extra_channels` channel set. After sending `irc.proto.join(...)` using the service bot's UID as a source, the bot should permanently remain on that channel throughout KILLs or disconnects.
+
+## Removing services on unload
+
+All plugins using the services API **MUST** have a `die()` function that unregisters all services that they've created. A simple example would be in the `games` plugin:
+
+```python
+def die(irc):
+    utils.unregisterService('games')
+```
+
+## Service bots and commands
+
+Commands for service bots and commands for the main PyLink bot have two main differences.
+
+1) Commands for service bots are bound using `myservice.add_cmd(cmdfunc, 'cmdname')` instead of `utils.add_cmd(...)`
+
+2) Replies for service bot commands are sent using `myservice.reply(irc, text)` instead of `irc.reply(...)`
+
+### Featured commands
+
+Commands for service bots can also be marked as *featured*, which shows it with its command arguments in the default `LIST` command. To mark a command as featured, use `myservice.add_cmd(cmdfunc, 'cmdname', featured=True)`.