More function comments

diff --git a/cron/cron-lib.pl b/cron/cron-lib.pl
index 641bfc0..588b506 100644 (file)
--- a/cron/cron-lib.pl
+++ b/cron/cron-lib.pl
@@ -1,6 +1,14 @@
 =head1 cron-lib.pl
 
-Common crontab functions
+Functions for listing, creating and managing Unix users' cron jobs.
+
+ foreign_require("cron", "cron-lib.pl");
+ @jobs = cron::list_cron_jobs();
+ $job = { 'user' => 'root',
+          'active' => 1,
+          'command' => 'ls -l >/dev/null',
+          'special' => 'hourly' };
+ cron::create_cron_job($job);
 
 =cut
 
@@ -222,6 +230,11 @@ closedir(DIR);
 return @cron_jobs_cache;
 }
 
+=head2 cron_job_line(&job)
+
+Internal function to generate a crontab format line for a cron job
+
+=cut
 sub cron_job_line
 {
 local @c;
@@ -355,7 +368,8 @@ foreach $j (@cron_jobs_cache) {
 
 =head2 renumber_index(index, offset)
 
-MISSING DOCUMENTATION
+Internal function to change the index of all cron jobs in the cache after
+some index by a given offset.
 
 =cut
 sub renumber_index
@@ -370,7 +384,8 @@ foreach $j (@cron_jobs_cache) {
 
 =head2 change_cron_job(&job)
 
-MISSING DOCUMENTATION
+Updates the given cron job, which must be a hash ref returned by list_cron_jobs
+and modified with a new active flag, command or schedule.
 
 =cut
 sub change_cron_job
@@ -389,7 +404,8 @@ else {
 
 =head2 delete_cron_job(&job)
 
-MISSING DOCUMENTATION
+Removes the cron job defined by the given hash ref, as returned by
+list_cron_jobs.
 
 =cut
 sub delete_cron_job
@@ -425,10 +441,9 @@ if (@tab >= 3 && $tab[0] =~ /DO NOT EDIT/ &&
 return @tab;
 }
 
-
 =head2 copy_crontab(user)
 
-Copy the cron temp file to that for this user
+Copy the cron temp file to that for this user. For internal use only.
 
 =cut
 sub copy_crontab
@@ -502,7 +517,7 @@ unlink($cron_temp_file);
 }
 
 
-=head2 parse_job(job)
+=head2 parse_job(job-line)
 
 Parse a crontab line into an array containing:
 active, mins, hrs, days, mons, weekdays, command
@@ -643,7 +658,8 @@ close(TAB);
 
 =head2 expand_run_parts(directory)
 
-MISSING DOCUMENTATION
+Internal function to convert a directory like /etc/cron.hourly into a list
+of scripts in that directory.
 
 =cut
 sub expand_run_parts
@@ -661,7 +677,8 @@ return @rv;
 
 =head2 is_run_parts(command)
 
-MISSING DOCUMENTATION
+Returns the dir if some cron job runs a list of commands in some directory, 
+like /etc/cron.hourly. Returns undef otherwise.
 
 =cut
 sub is_run_parts
@@ -672,7 +689,8 @@ return $rp && $_[0] =~ /$rp(.*)\s+([a-z0-9\.\-\/_]+)(\s*\))?$/i ? $2 : undef;
 
 =head2 can_edit_user(&access, user)
 
-MISSING DOCUMENTATION
+Returns 1 if the Webmin user whose permissions are defined by the access hash
+ref can manage cron jobs for a given Unix user.
 
 =cut
 sub can_edit_user
@@ -701,7 +719,10 @@ else {
 
 =head2 show_times_input(&job, [nospecial])
 
-MISSING DOCUMENTATION
+Print HTML for inputs for selecting the schedule for a cron job, defined
+by the first parameter which must be a hash ref returned by list_cron_jobs.
+This must be used inside a <table>, as the HTML starts and ends with <tr>
+tags.
 
 =cut
 sub show_times_input
@@ -818,7 +839,9 @@ print "</tr> <tr $cb> <td colspan=5>$text{'edit_ctrl'}</td> </tr>\n";
 
 =head2 parse_times_input(&job, &in)
 
-MISSING DOCUMENTATION
+Parses inputs from the form generated by show_times_input, and updates a cron
+job hash ref. The in parameter must be a hash ref as generated by the 
+ReadParse function.
 
 =cut
 sub parse_times_input
@@ -1177,7 +1200,8 @@ return 0;
 
 =head2 unconvert_range(&job)
 
-MISSING DOCUMENTATION
+Give a cron job with start and end fields, updates the command to wrap it in
+range.pl with those dates as parameters.
 
 =cut
 sub unconvert_range
@@ -1254,6 +1278,11 @@ if (!$single_user && !$fcron && !-d $config{'cron_dir'}) {
 return undef;
 }
 
+=head2 check_cron_config_or_error
+
+Calls check_cron_config, and then error if any problems were detected.
+
+=cut
 sub check_cron_config_or_error
 {
 local $err = &check_cron_config();