Merge lp:~mhall119/classbot/pod into lp:classbot

[Michael Hall]

Adds some initial POD code documentation

Unmerged revisions

99. By Michael Hall on 2011-03-28

Initial perldoc documentation effort

=== modified file 'classbot.pl'
--- classbot.pl	2011-01-26 22:48:29 +0000
+++ classbot.pl	2011-03-28 13:11:00 +0000
@@ -1,5 +1,16 @@
 #!/usr/bin/perl
 
+=pod
+
+=head1 NAME
+
+classbot - Ubuntu Classroom Helper
+
+=head1 DESCRIPTION
+
+ClassBot is a bot to assist with the running of sessions in #ubuntu-classroom'
+
+=cut
 use strict;
 use vars qw($VERSION %IRSSI);
 use LWP::Simple;
@@ -532,6 +543,13 @@
 	}
 }
 
+=head1 EVENT HANDLERS
+
+=over
+
+=item client_join($server, $channel, $nick, $host)
+
+=cut
 sub client_join {
 	my ($server, $channel, $nick, $host) = @_;
 	$channel =~ s/^://;
@@ -628,6 +646,25 @@
 	$server->command("^MSG ChanServ TOPIC $chan $text");
 }
 
+=item event_privmsg($server, $data, $nick, $address)
+
+Handles private messages sent to the bot.
+
+=over
+
+=item server
+
+=item nick
+
+=item address
+
+=item data
+
+This comes as a string formatted as "B<target>: B<text>". 
+
+=over
+
+=cut
 sub event_privmsg {
 	# $data = "nick/#channel :text"
 	my ($server, $data, $nick, $address) = @_;
@@ -638,6 +675,12 @@
 	utf8::decode($text);
 	utf8::decode($mynick);
 
+=item QUESTION:
+
+When "target" is the question channel, and B<text> starts with the
+ "QUESTION:" prefix, then "text" is added to the questions queue.
+
+=cut
 	#TRANSLATORS: QUESTION: is the prefix that must go before all questions in the -chat IRC channel ($qchan) for ClassBot to recognize them.	
 	my $qprefix=$d->get("QUESTION:");
 	if($target =~ m/^$qchan$/i && $text =~ m/^$qprefix\s*(.*)$/i) {
@@ -647,6 +690,18 @@
 		#TRANSLATORS: The first %s is the nickname of the person who asked the question. The second %s is the question that was asked.
 		push(@questions,sprintf($d->get("%s asked: %s"), $nick, $question));
 	}
+
+=item Commands
+
+When "target" is the nick of the bot, then B<text> is treated like a command.
+
+=over
+
+=item !logs
+
+When B<text> is B<!logs>, the bot will respond with links to the session logs.
+
+=cut
 	elsif($text =~ m/^!logs?\s*$/i) {
 		if($session !~ m/^\s*$/) {
 			for my $key ( keys %sessions ) {
@@ -684,6 +739,12 @@
 			}
 		}
 	}
+
+=item !question, !q
+
+Shows the next question in the queue for the instructor to accept or reject.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && ($leaders{lc($nick)} || $shelpers{lc($nick)} || $admins{lc($nick)}) && $text =~ m/^!(question|q)$/i) {
 		if($review ne '') {
 			Irssi::print("$nick must finish reviewing $review before they can do !question.")	if($debug);
@@ -706,6 +767,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!question).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently a session leader, so you cannot use %s."), "!question"));
 	}
+
+=item !yes, !y
+
+Tells the bot to post the next question in the queue into the classroom channel
+
+=cut
 	elsif($target =~ m/^$mynick$/i && ($leaders{lc($nick)} || $shelpers{lc($nick)} || $admins{lc($nick)}) && $text =~ m/^!(yes|y)$/i) {
 		if($review ne '') {
 			my($channel)=$server->channel_find($chan);
@@ -729,6 +796,13 @@
 		#TRANSLATORS: The %s represents a special bot command (!yes).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently a session leader, so you cannot use %s."), "!yes"));
 	}
+
+=item !no [reason], !n [reason]
+
+Rejects the next question in the queue, any text after the command will be
+ posted into the questions channel as a reason for the rejection.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && ($leaders{lc($nick)} || $shelpers{lc($nick)} || $admins{lc($nick)}) && $text =~ m/^!(no|n)\s*(.*?)$/i) {
 		my $comment = $2;
 		utf8::decode($comment);
@@ -750,6 +824,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!no).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently a session leader, so you cannot use %s."), "!no"));
 	}
+
+=item !moderate, $m
+
+Toggles the classroom channel's moderation (+m) status.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && ($leaders{lc($nick)} || $shelpers{lc($nick)} || $admins{lc($nick)}) && $text =~ m/^!(moderate|m)$/i) {
 		my($channel)=$server->channel_find($chan);
 		my($mode)=$channel->{'mode'};
@@ -769,6 +849,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!moderate).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently a session leader, so you cannot use %s."), "!moderate"));
 	}
+
+=item !schedule, !s
+
+Returns the next 3 scheduled classroom sessions.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $text =~ m/^!(schedule|s)$/i) {
 		if($#sessions < 0) {
 			$server->command("MSG $nick ".$d->get("There are currently no scheduled classes."));
@@ -777,6 +863,12 @@
 			$server->command("MSG $nick ".sprintf($d->get("The next 3 scheduled classroom sessions are: %s"), join(', ', @sessions)));
 		}
 	}
+
+=item !voice [person], !v [person]
+
+Gives the specified person voice (+v) in the classroom channel
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!(voice|v)\s*(.*?)$/i) {
 		my $person = $2;
 		utf8::decode($person);
@@ -793,6 +885,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!voice).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!voice"));
 	}
+
+=item !devoice [person], !dv [person]
+
+Removes voice (+v) from the specified person in the classroom channel
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!(devoice|dv)\s*(.*?)$/i) {
 		my $person = $2;
 		utf8::decode($person);
@@ -809,6 +907,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!devoice).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!devoice"));
 	}
+
+=item !calendar, !cal, !c
+
+Imports the classroom schedule from the ical source
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!(calendar|cal|c)$/i) {
 		Irssi::print("Forced download of calendar triggered by $nick") if($debug);
 		$server->command("^MSG $nick ".$d->get("Forcing download of calendar."));
@@ -820,6 +924,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!calendar).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!calendar"));
 	}
+
+=item !topic [text], !t [text]
+
+Sets the classroom channel topic to the given text.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!(topic|t)\s*(.*?)$/i) {
 		Irssi::print("Setting classroom_topic to: $2")	if($debug);
 		Irssi::settings_set_str('classroom_topic', "$2");
@@ -830,6 +940,12 @@
 		#TRANSLATORS: The %s represents a special bot command (!topic).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!topic"));
 	}
+
+=item !qtopic [text], !qt [text]
+
+Sets the question channel topic to the given text.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!(qtopic|qt)\s*(.*?)$/i) {
                 Irssi::print("Setting classroom_qtopic to: $2")  if($debug);
                 Irssi::settings_set_str('classroom_qtopic', "$2");
@@ -840,6 +956,13 @@
                 #TRANSLATORS: The %s represents a special bot command (!qtopic).
                 $server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!qtopic"));
         }
+
+=item !dent [msg]
+
+Sends the given message to Identi.ca using the bot's configured identi.ca 
+ username and password
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $admins{lc($nick)} && $text =~ m/^!dent\s*(.*?)$/i) {
 		my $dent_text = $1;
 		utf8::decode($dent_text);
@@ -858,6 +981,13 @@
 		#TRANSLATORS: The %s represents a special bot command (!dent).
 		$server->command("^MSG $nick ".sprintf($d->get("You are not currently an admin, so you cannot use %s."), "!dent"));
 	}
+
+=item !admin [msg]
+
+Sends a message to the backstage channel requesting assistance, along with an
+ optional message.
+
+=cut
 	elsif($target =~ m/^$mynick$/i && $text =~ m/^!(admin|a)\s*(.*?)$/i) {
 		my $admin_msg = $2;
 		utf8::decode($admin_msg);
@@ -881,6 +1011,17 @@
 	}
 }
 
+=back
+
+=back
+
+=back
+
+=item cmd_help($data, $server, $witem)
+
+Prints Classbot usage information
+
+=cut
 sub cmd_help {
 	my($data, $server, $witem) = @_;
 
@@ -900,7 +1041,28 @@
 	}
 }
 
+=back
+
+=cut
 Irssi::signal_add("setup changed", "refresh_settings");
 Irssi::signal_add("event privmsg", "event_privmsg");
 Irssi::signal_add("message join", "client_join");
 Irssi::command_bind_last('help', 'cmd_help');
+
+=head1 AUTHORS
+
+Nathan Handler <[e-mail]>
+
+L<https://launchpad.net/~nhandler>
+
+=head1 BUGS
+
+L<https://bugs.launchpad.net/classbot/>
+
+=head1 SEE ALSO
+
+L<Irssi>
+
+=head2 COPYRIGHT
+
+GNU GPL v3