--- loncom/interface/lonmsg.pm	2003/07/05 10:07:11	1.57
+++ loncom/interface/lonmsg.pm	2003/07/25 01:18:04	1.58
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Routines for messaging
 #
-# $Id: lonmsg.pm,v 1.57 2003/07/05 10:07:11 www Exp $
+# $Id: lonmsg.pm,v 1.58 2003/07/25 01:18:04 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -44,6 +44,68 @@
 #
 package Apache::lonmsg;
 
+=pod
+
+=head1 NAME
+
+Apache::lonmsg: supports internal messaging
+
+=head1 SYNOPSIS
+
+lonmsg provides routines for sending messages, receiving messages, and
+a handler to allow users to read, send, and delete messages.
+
+=head1 OVERVIEW
+
+=head2 Messaging Overview
+
+X<messages>LON-CAPA provides an internal messaging system similar to
+email, but customized for LON-CAPA's usage. LON-CAPA implements its
+own messaging system, rather then building on top of email, because of
+the features LON-CAPA messages can offer that conventional e-mail can
+not:
+
+=over 4
+
+=item * B<Critical messages>: A message the recipient B<must>
+acknowlegde receipt of before they are allowed to continue using the
+system, preventing a user from claiming they never got a message
+
+=item * B<Receipts>: LON-CAPA can reliably send reciepts informing the
+sender that it has been read; again, useful for preventing students
+from claiming they did not see a message. (While conventional e-mail
+has some reciept support, it's sporadic, e-mail client-specific, and
+generally the receiver can opt to not send one, making it useless in
+this case.)
+
+=item * B<Context>: LON-CAPA knows about the sender, such as where
+they are in a course. When a student mails an instructor asking for
+help on the problem, the instructor receives not just the student's
+question, but all submissions the student has made up to that point,
+the user's rendering of the problem, and the complete view the student
+saw of the resource, including discussion up to that point. Finally,
+the instructor is reading all of this inside of LON-CAPA, not their
+email program, so they have full access to LON-CAPA's grading
+interface, or other features they may wish to use in response to the
+student's query.
+
+=back
+
+Users can ask LON-CAPA to forward messages to conventional e-mail
+addresses on their B<PREF> screen, but generally, LON-CAPA messages
+are much more useful then traditional email can be made to be, even
+with HTML support.
+
+Right now, this document will cover just how to send a message, since
+it is likely you will not need to programmatically read messages,
+since lonmsg already implements that functionality.
+
+=head1 FUNCTIONS
+
+=over 4
+
+=cut
+
 use strict;
 use Apache::lonnet();
 use vars qw($msgcount);
@@ -192,6 +254,13 @@ sub newmail {
 
 # =============================== Automated message to the author of a resource
 
+=pod
+
+=item * B<author_res_msg($filename, $message)>: Sends message $message to the owner
+    of the resource with the URI $filename.
+
+=cut
+
 sub author_res_msg {
     my ($filename,$message)=@_;
     unless ($message) { return 'empty'; }
@@ -255,6 +324,14 @@ sub user_crit_msg_raw {
 
 # New routine that respects "forward" and calls old routine
 
+=pod
+
+=item * B<user_crit_msg($user, $domain, $subject, $message, $sendback)>: Sends
+    a critical message $message to the $user at $domain. If $sendback is true,
+    a reciept will be sent to the current user when $user recieves the message.
+
+=cut
+
 sub user_crit_msg {
     my ($user,$domain,$subject,$message,$sendback)=@_;
     my $status='';
@@ -335,6 +412,14 @@ sub user_normal_msg_raw {
 
 # New routine that respects "forward" and calls old routine
 
+=pod
+
+=item * B<user_normal_msg($user, $domain, $subject, $message,
+    $citation, $baseurl, $attachmenturl)>: Sends a message to the
+    $user at $domain, with subject $subject and message $message.
+
+=cut
+
 sub user_normal_msg {
     my ($user,$domain,$subject,$message,$citation,$baseurl,$attachmenturl)=@_;
     my $status='';
@@ -970,6 +1055,12 @@ BEGIN {
     $msgcount=0;
 }
 
+=pod
+
+=back
+
+=end
+
 1;
 __END__