--- loncom/LONCAPA.pm	2007/07/02 21:15:29	1.24
+++ loncom/LONCAPA.pm	2008/11/17 13:22:01	1.25
@@ -1,7 +1,7 @@
 # The LearningOnline Network
 # Base routines
 #
-# $Id: LONCAPA.pm,v 1.24 2007/07/02 21:15:29 albertel Exp $
+# $Id: LONCAPA.pm,v 1.25 2008/11/17 13:22:01 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -27,6 +27,42 @@
 #
 ###
 
+=head1 NAME
+
+Apache::LONCAPA
+
+LONCAPA - Basic routines
+
+=head1 SYNOPSIS
+
+Generally useful routines
+
+=head1 EXPORTED SUBROUTINES
+
+=over 4
+
+=item *
+
+escape() : unpack non-word characters into CGI-compatible hex codes
+
+=item *
+
+unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
+
+=item *
+
+add_get_param() :
+ Inputs:  url (with or without exit GET from parameters), hash ref of
+              form name => value pairs
+
+ Return: url with properly added the form name elements and values to the 
+         the url doing proper escaping of the values and joining with ? or &
+         as needed
+
+=back
+
+=cut
+
 package LONCAPA;
 
 use strict;
@@ -170,26 +206,32 @@ sub propath {
 
 
 #---------------------------------------------------------------
-#
-# Manipulation of hash based databases (factoring out common code
-# for later use as we refactor.
-#
-#  Ties a domain level resource file to a hash.
-#  If requested a history entry is created in the associated hist file.
-#
-#  Parameters:
-#     domain    - Name of the domain in which the resource file lives.
-#     namespace - Name of the hash within that domain.
-#     how       - How to tie the hash (e.g. GDBM_WRCREAT()).
-#     loghead   - Optional parameter, if present a log entry is created
-#                 in the associated history file and this is the first part
-#                  of that entry.
-#     logtail   - Goes along with loghead,  The actual logentry is of the
-#                 form $loghead:<timestamp>:logtail.
-# Returns:
-#    Reference to a hash bound to the db file or alternatively undef
-#    if the tie failed.
-#
+
+=pod
+
+=item tie_domain_hash()
+
+Manipulation of hash based databases (factoring out common code
+for later use as we refactor.
+
+ Ties a domain level resource file to a hash.
+ If requested a history entry is created in the associated hist file.
+
+ Parameters:
+    domain    - Name of the domain in which the resource file lives.
+    namespace - Name of the hash within that domain.
+    how       - How to tie the hash (e.g. GDBM_WRCREAT()).
+    loghead   - Optional parameter, if present a log entry is created
+                in the associated history file and this is the first part
+                 of that entry.
+    logtail   - Goes along with loghead,  The actual logentry is of the
+                form $loghead:<timestamp>:logtail.
+Returns:
+   Reference to a hash bound to the db file or alternatively undef
+   if the tie failed.
+
+=cut
+
 sub tie_domain_hash {
     my ($domain,$namespace,$how,$loghead,$logtail) = @_;
     
@@ -208,25 +250,31 @@ sub tie_domain_hash {
 sub untie_domain_hash {
     return &_locking_hash_untie(@_);
 }
-#
-#   Ties a user's resource file to a hash.  
-#   If necessary, an appropriate history
-#   log file entry is made as well.
-#   This sub factors out common code from the subs that manipulate
-#   the various gdbm files that keep keyword value pairs.
-# Parameters:
-#   domain       - Name of the domain the user is in.
-#   user         - Name of the 'current user'.
-#   namespace    - Namespace representing the file to tie.
-#   how          - What the tie is done to (e.g. GDBM_WRCREAT().
-#   loghead      - Optional first part of log entry if there may be a
-#                  history file.
-#   what         - Optional tail of log entry if there may be a history
-#                  file.
-# Returns:
-#   hash to which the database is tied.  It's up to the caller to untie.
-#   undef if the has could not be tied.
-#
+
+=pod
+
+=item tie_user_hash()
+
+  Ties a user's resource file to a hash.  
+  If necessary, an appropriate history
+  log file entry is made as well.
+  This sub factors out common code from the subs that manipulate
+  the various gdbm files that keep keyword value pairs.
+Parameters:
+  domain       - Name of the domain the user is in.
+  user         - Name of the 'current user'.
+  namespace    - Namespace representing the file to tie.
+  how          - What the tie is done to (e.g. GDBM_WRCREAT().
+  loghead      - Optional first part of log entry if there may be a
+                 history file.
+  what         - Optional tail of log entry if there may be a history
+                 file.
+Returns:
+  hash to which the database is tied.  It's up to the caller to untie.
+  undef if the has could not be tied.
+
+=cut
+
 sub tie_user_hash {
     my ($domain,$user,$namespace,$how,$loghead,$what) = @_;
 
@@ -241,8 +289,14 @@ sub untie_user_hash {
     return &_locking_hash_untie(@_);
 }
 
-# routines if you just have a filename
-# return tied hashref or undef
+=pod
+
+=item locking_hash_tie()
+
+routines if you just have a filename
+return tied hashref or undef
+
+=cut
 
 sub locking_hash_tie {
     my ($filename,$how)=@_;
@@ -416,36 +470,4 @@ BEGIN {
 
 __END__
 
-=pod
-
-=head1 NAME
-
-LONCAPA - Basic routines
 
-=head1 SYNOPSIS
-
-Generally useful routines
-
-=head1 EXPORTED SUBROUTINES
-
-=over 4
-
-=item *
-
-escape() : unpack non-word characters into CGI-compatible hex codes
-
-=item *
-
-unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
-
-=item *
-
-add_get_param() :
- Inputs:  url (with or without exit GET from parameters), hash ref of
-              form name => value pairs
-
- Return: url with properly added the form name elements and values to the 
-         the url doing proper escaping of the values and joining with ? or &
-         as needed
-
-=back