--- connect() - start a connection to the irc server {{{
--- args: network - address of the irc network to connect to
--- port - port to connect to
--- pass - irc server password (if required)
--- nick - nickname to connect as
--- username - username to connect with
--- realname - realname to connect with
--- timeout - amount of time in seconds to wait before dropping an idle
--- connection
--- notes: this function uses a table and named arguments. defaults are specified
--- by the capitalized versions of the arguments at the top of this file.
--- all args are optional.
+-- connect {{{
+---
+-- Start a connection to the irc server.
+-- @param args Table of named arguments containing connection parameters.
+-- Defaults are the all-caps versions of these parameters given
+-- at the top of the file, and are overridable by setting them
+-- as well, i.e. <pre>irc.NETWORK = irc.freenode.net</pre>
+-- Possible options are:
+-- <ul>
+-- <li><i>network:</i> address of the irc network to connect to
+-- (default: 'localhost')</li>
+-- <li><i>port:</i> port to connect to
+-- (default: '6667')</li>
+-- <li><i>pass:</i> irc server password
+-- (default: don't send)</li>
+-- <li><i>nick:</i> nickname to connect as
+-- (default: 'luabot')</li>
+-- <li><i>username:</i> username to connect with
+-- (default: 'LuaIRC')</li>
+-- <li><i>realname:</i> realname to connect with
+-- (default: 'LuaIRC')</li>
+-- <li><i>timeout:</i> amount of time in seconds to wait before
+-- dropping an idle connection
+-- (default: '60')</li>
+-- </ul>