docs: tweak writing-plugins & TOC, move plugin_example to plugins

Closes #226.

docs/technical/README.md

@@ -23,3 +23,4 @@ PyLink is an a modular, plugin-based IRC services framework. It uses swappable p
 ### Future topics (not yet available)
 - [Writing tests for PyLink modules](writing-tests.md)
 - [Supported named user modes](user-modes.csv)
+- [Services bot API/Creating your own service bots](services-api.md)

docs/technical/writing-plugins.md

@@ -2,7 +2,7 @@
 
 PyLink plugins are modules that extend its functionality by giving it something to do. Without any plugins loaded, PyLink can only sit on a server and do absolutely nothing.
 
-This guide, along with the sample plugin [`plugin_example.py`](plugin_example.py), aim to show the basics of writing plugins for PyLink.
+This guide, along with the sample plugins [`plugins/example.py`](../../plugins/example.py), and [`plugins/service.py`](../../plugins/demo_service.py) aim to show the basics of writing plugins for PyLink.
 
 ## Receiving data from IRC
 
@@ -28,7 +28,7 @@ Hook functions do not return anything, and can raise exceptions to be caught by
 
 ### Bot commands
 
-For plugins that interact with regular users, you can simply write commands for the PyLink bot.
+For plugins that interact with regular users, you can also write commands for the PyLink bot, or [create service bots with their own command set](services-api.md). This section only details the former:
 
 Plugins can add commands by including something like `utils.add_cmd(testcommand, "hello")`. Here, `testcommand` is the name of your function, and `hello` is the (optional) name of the command. If no command name is specified, it will use the same name as the function.
 Now, your command function will be called whenever someone PMs the PyLink client with the command (e.g. `/msg PyLink hello`, case-insensitive).
@@ -42,7 +42,7 @@ Each command function takes 3 arguments: `irc, source, args`.
 
 Command handlers do not return anything and can raise exceptions, which are caught by the core and automatically return an error message.
 
-### Sending data to IRC
+## Sending data to IRC
 
 Plugins receive data from the underlying protocol module, and communicate back using outgoing [command functions](pmodule-spec.md) implemented by the protocol module. They should *never* send raw data directly back to IRC, because that wouldn't be portable across different IRCds.
 

plugins/example.py

@@ -1,4 +1,4 @@
-# plugin_example.py: An example PyLink plugin.
+# example.py: An example PyLink plugin.
 
 # These two lines add PyLink's root directory to the PATH, so that importing things like
 # 'utils' and 'log' work.
@@ -23,11 +23,15 @@ import random
 def hook_privmsg(irc, source, command, args):
     channel = args['target']
     text = args['text']
+
     # irc.pseudoclient stores the IrcUser object of the main PyLink client.
     # (i.e. the user defined in the bot: section of the config)
     if utils.isChannel(channel) and irc.pseudoclient.nick in text:
         irc.msg(channel, 'hi there!')
+        # log.debug, log.info, log.warning, log.error, log.exception (within except: clauses)
+        # and log.critical are supported here.
         log.info('%s said my name on channel %s (PRIVMSG hook caught)' % (source, channel))
+
 utils.add_hook(hook_privmsg, 'PRIVMSG')
 
 
@@ -41,7 +45,11 @@ def randint(irc, source, args):
     # The docstring here is used as command help by the 'help' command, and formatted using the
     # same line breaks as the raw string. You shouldn't make this text or any one line too long,
     # to prevent flooding users or getting long lines cut off.
-    """[<min>] [<max>]
+
+    # The same applies to message replies in general: plugins sending long strings of text should
+    # be wary that long messages can get cut off. Automatic word-wrap may be added in the future:
+    # https://github.com/GLolol/PyLink/issues/153
+    """[<min> <max>]
     Returns a random number between <min> and <max>. <min> and <max> default
     to 1 and 10 respectively, if both aren't given."""
     try:
@@ -58,6 +66,4 @@ def randint(irc, source, args):
 
 # You can also bind a command function multiple times, and/or to different command names via a
 # second argument.
-# Note: no checking is done at the moment to prevent multiple plugins from binding to the same
-# command name. The older command just gets replaced by the new one!
 utils.add_cmd(randint, "random")