From 889fa61521c9c31c076072f2f8dd45466302781a Mon Sep 17 00:00:00 2001
From: Doug Bell <doug@plainblack.com>
Date: Fri, 25 Jun 2010 13:53:15 -0500
Subject: [PATCH] add docs to WebGUI::Auth::Twitter

---
 lib/WebGUI/Auth/Twitter.pm | 90 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/lib/WebGUI/Auth/Twitter.pm b/lib/WebGUI/Auth/Twitter.pm
index 28861f2e0..707799292 100644
--- a/lib/WebGUI/Auth/Twitter.pm
+++ b/lib/WebGUI/Auth/Twitter.pm
@@ -1,14 +1,60 @@
 package WebGUI::Auth::Twitter;
 
+=head1 LEGAL
+
+ -------------------------------------------------------------------
+  WebGUI is Copyright 2001-2009 Plain Black Corporation.
+ -------------------------------------------------------------------
+  Please read the legal notices (docs/legal.txt) and the license
+  (docs/license.txt) that came with this distribution before using
+  this software.
+ -------------------------------------------------------------------
+  http://www.plainblack.com                     info@plainblack.com
+ -------------------------------------------------------------------
+
+=cut
+
 use strict;
 use base 'WebGUI::Auth';
 use Net::Twitter;
 
+=head1 NAME
+
+WebGUI::Auth::Twitter -- Twitter auth for WebGUI
+
+=head1 DESCRIPTION
+
+Allow WebGUI to authenticate to WebGUI
+
+=head1 METHODS
+
+These methods are available from this class:
+
+=cut
+
+#----------------------------------------------------------------------------
+
+=head2 new ( ... )
+
+Create a new object
+
+=cut
+
 sub new {
     my $self    = shift->SUPER::new(@_);
     return bless $self, __PACKAGE__; # Auth requires rebless
 }
 
+#----------------------------------------------------------------------------
+
+=head2 createTwitterUser ( twitterUserId, username )
+
+    my $user    = $self->createTwitterUser( $twitterUserId, $username );
+
+Create a new Auth::Twitter user with the given twitter userId and screen name.
+
+=cut
+
 sub createTwitterUser {
     my ( $self, $twitterUserId, $twitterScreenName ) = @_;
     my $user    = WebGUI::User->create( $self->session );
@@ -19,6 +65,14 @@ sub createTwitterUser {
     return $user;
 }
 
+#----------------------------------------------------------------------------
+
+=head2 editUserSettingsForm ( )
+
+Return the form to edit the settings of this Auth module
+
+=cut
+
 sub editUserSettingsForm {
     my $self = shift;
     my $session = $self->session;
@@ -51,6 +105,14 @@ sub editUserSettingsForm {
     return $f->printRowsOnly;
 }
 
+#----------------------------------------------------------------------------
+
+=head2 editUserSettingsFormSave ( )
+
+Process the form for this Auth module's settings
+
+=cut
+
 sub editUserSettingsFormSave {
     my $self    = shift;
     my $session = $self->session;
@@ -64,6 +126,14 @@ sub editUserSettingsFormSave {
     return;
 }
 
+#----------------------------------------------------------------------------
+
+=head2 www_login ( )
+
+Begin the login procedure
+
+=cut
+
 sub www_login {
     my ( $self ) = @_;
     my $session = $self->session;
@@ -86,6 +156,17 @@ sub www_login {
     return "redirect";
 }
 
+#----------------------------------------------------------------------------
+
+=head2 www_callback ( )
+
+Callback from the Twitter authentication. Try to log the user in, creating a 
+new user account if necessary. 
+
+If the username is taken, allow the user to choose a new one.
+
+=cut
+
 sub www_callback {
     my ( $self ) = @_;
     my $session = $self->session;
@@ -138,6 +219,15 @@ sub www_callback {
     return $output;
 }
 
+#----------------------------------------------------------------------------
+
+=head2 www_setUsername ( )
+
+Set the username for a twitter user. Only used as part of the initial twitter
+registration.
+
+=cut
+
 sub www_setUsername {
     my ( $self ) = @_;
     my $session = $self->session;