added some stuff to the guide, and cleaned up some irssi.pod function descs

9 files changed, 137 insertions, 60 deletions

diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index fc7e81f..97e4799 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -27,6 +27,8 @@ This documentation has been split into a number of pages, each documenting a
 particular class or pseudo-class.  The following list contains all of these
 additional pages.
 
+B<TODO: fix this list with proper package names>
+
 =over 4
 
 =item L<Irssi::Ban>
@@ -131,6 +133,7 @@ returns a list of all L<ignores|Irssi::Ignore>.
 
 =head3 C<dccs>
 
+B<TODO: this shouldn't be here>
 returns a list of all L<DCC connections|Irssi::Irc::Dcc>
 
 =head2 Signals
@@ -282,6 +285,20 @@ Bind a command string C<$cmd> to call function C<$func>. C<$func> can be
 either a string or coderef. C<$category> is an optional string specifying
 the category to display the command in when C</HELP> is used.
 
+When a command is invoked, either by the user typing C</command args>, the
+handler function will be called.
+
+It will receive the following parameters, passed in C<@_>:
+
+    my ($argument_string, $server_obj, $window_item_obj) = @_;
+
+The argument string must be processed by the handler to split it into
+individual words if necessary.
+
+The L<command_parse_options|/command_parse_options $cmd, $data> function can be
+used to process options (beginning with a single dash), and will also return the
+remainder of the string to be processed as desired.
+
 =head4 C<command_runsub $cmd, $data, $server, $item>
 
 Run subcommands for `cmd'. First word in `data' is parsed as
@@ -291,7 +308,8 @@ L<Irssi::Windowitem> `item'.
 Call command_runsub in handler function for `cmd' and bind
 with command_bind("`cmd' `subcmd'", subcmdfunc[, category]);
 
-B<TODO: example here>
+See the L<example|Guide/Use Subcommands to Group Script Functionality> for
+further details.
 
 =head4 C<command_unbind $cmd, $func>
 
@@ -365,40 +383,43 @@ For example:
 
 =head2 Settings
 
+Settings are a way to permanently store values that your script may wish to use.
+They are also easily manipulable by the user through the C</SET> command, making
+them a good way to allow configuration of your script.
 
 =head3 Creating New Settings
 
-=head4 C<settings_add_str(section, key, def)>
+If a setting does not currently exist, it must first be registered with Irssi
+using one of the C<settings_add> functions.
 
-=head4 C<settings_add_int(section, key, def)>
+=head4 C<settings_add_str $section, $key, $def>
 
-=head4 C<settings_add_bool(section, key, def)>
+=head4 C<settings_add_int $section, $key, $def>
 
-=head4 C<settings_add_time(section, key, def)>
+=head4 C<settings_add_bool $section, $key, $def>
 
-=head4 C<settings_add_level(section, key, def)>
+=head4 C<settings_add_time $section, $key, $def>
 
-=head4 C<settings_add_size(section, key, def)>
+=head4 C<settings_add_level $section, $key, $def>
 
+=head4 C<settings_add_size $section, $key, $def>
 
 =head3 Retrieving Settings
 
-=head4 C<settings_get_str($key)>
+=head4 C<settings_get_str $key>
 
-=head4 C<settings_get_int($key)>
+=head4 C<settings_get_int $key>
 
-=head4 C<settings_get_bool($key)>
+=head4 C<settings_get_bool $key>
 
-=head4 C<settings_get_time($key)>
+=head4 C<settings_get_time $key>
 
-=head4 C<settings_get_level($key)>
+=head4 C<settings_get_level $key>
 
-=head4 C<settings_get_size($key)>
+=head4 C<settings_get_size $key>
 
 =head3 Modifying Settings
 
-Set value for setting.
-
 B<If you change the settings of another module/script with one of these, you
 must emit a C<"setup changed"> signal afterwards.>
 
diff --git a/docs/Irssi/Ignore.pod b/docs/Irssi/Ignore.pod
index 108c0ba..f93cbe3 100644
--- a/docs/Irssi/Ignore.pod
+++ b/docs/Irssi/Ignore.pod
@@ -7,6 +7,7 @@ Irssi::Ignore
 =head1 FIELDS
 
 Ignore->{}
+
   mask - Ignore mask
   servertag - Ignore only in server
   channels - Ignore only in channels (list of names)
diff --git a/docs/Irssi/Irc.pod b/docs/Irssi/Irc.pod
new file mode 100644
index 0000000..e51b190
--- /dev/null
+++ b/docs/Irssi/Irc.pod
@@ -0,0 +1,27 @@
+__END__
+
+=head1 NAME
+
+Irssi::Irc
+
+=head1 DESCRIPTION
+
+=head1 CLASSES
+
+=head1 EXPORTS
+
+=head1 METHODS
+
+=head2 Accessors
+
+=head3 C<dccs>
+
+returns a list of all L<DCC connections|Irssi::Irc::Dcc>
+
+=head1 COPYRIGHT
+
+All the content of this site is copyright E<copy> 2000-2010 L<The Irssi
+project|http://irssi.org>.
+
+Formatting to POD and linking by Tom Feist
+ L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org>
diff --git a/docs/Irssi/Irc/Ban.pod b/docs/Irssi/Irc/Ban.pod
index ba8381f..7026ca1 100644
--- a/docs/Irssi/Irc/Ban.pod
+++ b/docs/Irssi/Irc/Ban.pod
@@ -2,14 +2,14 @@ __END__
 
 =head1 NAME
 
-Irssi::Ban
+Irssi::Irc::Ban
 
 =head1 FIELDS
 
 Ban->{}
+
   ban - The ban
   setby - Nick of who set the ban
   time - Timestamp when ban was set
 
-
 =head1 METHODS
diff --git a/docs/Irssi/Irc/Client.pod b/docs/Irssi/Irc/Client.pod
index e07bed7..e0a27f4 100644
--- a/docs/Irssi/Irc/Client.pod
+++ b/docs/Irssi/Irc/Client.pod
@@ -2,10 +2,12 @@ __END__
 
 =head1 NAME
 
-Irssi::Client
+Irssi::Irc::Client
 
 =head1 FIELDS
+
 Client->{}
+
   nick - nick of the client
   host - host of the client
   proxy_address - address of the proxy server
@@ -16,5 +18,4 @@ Client->{}
   want_ctcp - whether the client wants to receive CTCPs
   ircnet - network tag of the network we proxy
 
-
 =head1 METHODS
diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod
index d7ab4a3..5950a92 100644
--- a/docs/Irssi/Irc/Dcc.pod
+++ b/docs/Irssi/Irc/Dcc.pod
@@ -2,7 +2,7 @@ __END__
 
 =head1 NAME
 
-Irssi::Dcc
+Irssi::Irc::Dcc
 
 =head1 FIELDS
 
diff --git a/docs/Irssi/Irc/Notifylist.pod b/docs/Irssi/Irc/Notifylist.pod
index 5b2628a..fd933ef 100644
--- a/docs/Irssi/Irc/Notifylist.pod
+++ b/docs/Irssi/Irc/Notifylist.pod
@@ -2,11 +2,12 @@ __END__
 
 =head1 NAME
 
-Irssi::Notifylist
+Irssi::Irc::Notifylist
 
 =head1 FIELDS
 
 Notifylist->{}
+
   mask - Notify nick mask
   away_check - Notify away status changes
   idle_check_time - Notify when idle time is reset and idle was bigger
@@ -16,6 +17,7 @@ Notifylist->{}
 
 =head1 METHODS
 
-Notifylist::ircnets_match(ircnet)
-  Returns 1 if notify is checked in `ircnet'.
+=head2 C<ircnets_match $ircnet>
+
+Returns 1 if notify is checked in `ircnet'.
 
diff --git a/docs/Irssi/UI/Window.pod b/docs/Irssi/UI/Window.pod
index a00827e..aa601a8 100644
--- a/docs/Irssi/UI/Window.pod
+++ b/docs/Irssi/UI/Window.pod
@@ -6,7 +6,8 @@ Irssi::UI::Window
 
 =head1 FIELDS
 
-UI::Window->{}
+C<UI::Window-E<gt>{}>
+
   refnum - Reference number
   name - Name
 
@@ -33,7 +34,8 @@ UI::Window->{}
 
   theme_name - Active theme in window, undef = default
 
-UI::TextDest->{}
+C<UI::TextDest-E<gt>{}>
+
   window - Window where the text will be written
   server - Target server
   target - Target channel/query/etc name
@@ -45,72 +47,92 @@ UI::TextDest->{}
 
 =head1 METHODS
 
-Window::command(cmd)
-Window::print(str[, level])
+=head2 C<command $cmd>
 
+=head2 C<print $str, [$level]>
 
-Window::items()
-  Return a list of items in window.
+=head2 C<items>
+
+Return a list of items in window.
 
-Window
-window_create(automatic)
-Windowitem::window_create(automatic)
-  Create a new window.
 
-Window::destroy()
-  Destroy the window.
+=head2 C<window_create $automatic>
+
+=head2 C<destroy>
+
+Destroy the window.
 
 Irssi::Window
 Windowitem::window()
   Returns parent window for window item.
 
-Window
-window_find_name(name)
-  Find window with name.
+=head2 C<window_find_name $name>
 
-Window
-window_find_refnum(refnum)
-  Find window with reference number.
+Find window with name.L<Irssi::UI::Window>
+
+=head2 C<window_find_refnum $refnum>
+
+Find window with reference number.
 
 Window
 window_find_level(level)
+
 Server::window_find_level(level)
   Find window with level.
 
 Window
 window_find_closest(name, level)
+
 Server::window_find_closest(name, level)
   Find window that matches best to given arguments. `name' can be either
   window name or name of one of the window items.
 
 Window
 window_find_item(name)
+
 Server::window_find_item(name)
   Find window which contains window item with specified name/server.
 
 
-Window::item_add(item, automatic)
-Window::item_remove(item)
-Window::item_destroy(item)
-  Add/remove/destroy window item
+=head2 C<item_add $item, $automatic>
+
+Add specified windowitem
+
+=head2 C<item_remove $item>
+
+remove specified windowitem
+
+=head2 C<item_destroy $item>
+
+destroy specified windowitem
+
+=head2 C<set_active>
+
+Set window active.
+
+=head2 C<change_server $server>
+
+=head2 C<set_refnum $refnum>
+
+=head2 C<set_name $name>
+
+=head2 C<set_history $name>
+
+=head2 C<set_level $level>
+
+Change server/refnum/name/history/level in window.
+
+=head2 C<item_prev>
+
+=head2 C<item_next>
 
-Window::set_active()
-  Set window active.
+Change to previous/next window item.
 
-Window::change_server(server)
-Window::set_refnum(refnum)
-Window::set_name(name)
-Window::set_history(name)
-Window::set_level(level)
-  Change server/refnum/name/history/level in window.
 
-Window::item_prev()
-Window::item_next()
-  Change to previous/next window item.
+=head2 C<get_active_name>
 
+Return active item's name, or if none is active, window's name
 
-Window::get_active_name()
-  Return active item's name, or if none is active, window's name
+=head2 C<item_find $server, $name>
 
-Window::item_find(server, name)
-  Find window item that matches best to given arguments.
+Find window item that matches best to given arguments.
diff --git a/docs/Irssi/Windowitem.pod b/docs/Irssi/Windowitem.pod
index f91183c..45cde9c 100644
--- a/docs/Irssi/Windowitem.pod
+++ b/docs/Irssi/Windowitem.pod
@@ -57,3 +57,6 @@ Returns 1 if window item is the active item in parent window.
 
 If `item' is a query of a =nick, return DCC chat record of nick.
 returns L<Irssi::Dcc> object.
+
+Windowitem::window_create(automatic)
+  Create a new window.