14 files changed, 98 insertions, 11 deletions
diff --git a/phpBB/includes/cron/lock.php b/phpBB/includes/cron/lock.php
index b2ba89ad6c..27b8b425c1 100644
--- a/phpBB/includes/cron/lock.php
+++ b/phpBB/includes/cron/lock.php
@@ -32,6 +32,11 @@ class phpbb_cron_lock
 	* Tries to acquire the cron lock by updating 
 	* the 'cron_lock' configuration variable in the database.
 	*
+	* As a lock may only be held by one process at a time, lock
+	* acquisition may fail if another process is holding the lock
+	* or if another process obtained the lock but never released it.
+	* Locks are forcibly released after a timeout of 1 hour.
+	*
 	* @return bool		true if lock was acquired
 	*					false otherwise
 	*/
@@ -76,9 +81,13 @@ class phpbb_cron_lock
 	}
 
 	/**
-	* Releases cron lock.
+	* Releases the cron lock.
+	*
+	* The lock must have been previously obtained, that is, lock() call
+	* was issued and returned true.
 	*
-	* Attempting to release a cron lock that is already released is harmless.
+	* Note: Attempting to release a cron lock that is already released,
+	* that is, calling unlock() multiple times, is harmless.
 	*
 	* @return void
 	*/
diff --git a/phpBB/includes/cron/manager.php b/phpBB/includes/cron/manager.php
index 1cbf4c1f72..4c7f59092f 100644
--- a/phpBB/includes/cron/manager.php
+++ b/phpBB/includes/cron/manager.php
@@ -55,7 +55,7 @@ class phpbb_cron_manager
 	*
 	* Todo: consider caching found task file list in global cache.
 	*
-	* @return array		Array of strings
+	* @return array		List of task names
 	*/
 	public function find_cron_task_names()
 	{
@@ -128,8 +128,11 @@ class phpbb_cron_manager
 
 	/**
 	* Finds a task that is ready to run.
+	*
 	* If several tasks are ready, any one of them could be returned.
 	*
+	* If no tasks are ready, null is returned.
+	*
 	* @return phpbb_cron_task_wrapper|null
 	*/
 	public function find_one_ready_task()
@@ -147,7 +150,7 @@ class phpbb_cron_manager
 	/**
 	* Finds all tasks that are ready to run.
 	*
-	* @return array		Array of phpbb_cron_task_wrapper
+	* @return array		List of tasks which are ready to run (wrapped in phpbb_cron_task_wrapper).
 	*/
 	public function find_all_ready_tasks()
 	{
@@ -164,9 +167,13 @@ class phpbb_cron_manager
 
 	/**
 	* Finds a task by name.
+	*
+	* If there is no task with the specified name, null is returned.
+	*
 	* Web runner uses this method to resolve names to tasks.
 	*
-	* @return array|null		Array of phpbb_cron_task_wrapper
+	* @param string				$name Name of the task to look up.
+	* @return phpbb_cron_task	A task corresponding to the given name, or null.
 	*/
 	public function find_task($name)
 	{
diff --git a/phpBB/includes/cron/task/base.php b/phpBB/includes/cron/task/base.php
index a4e89f137f..38c0b844d9 100644
--- a/phpBB/includes/cron/task/base.php
+++ b/phpBB/includes/cron/task/base.php
@@ -55,7 +55,16 @@ abstract class phpbb_cron_task_base implements phpbb_cron_task
 	/**
 	* Returns whether this cron task can be run in shutdown function.
 	*
-	* @return bool
+	* By the time shutdown sequence invokes a particular piece of code,
+	* resources that that code requires may already be released.
+	* If so, a particular cron task may be marked shutdown function-
+	* unsafe, and it will be executed in normal program flow.
+	*
+	* Generally speaking cron tasks should start off as shutdown function-
+	* safe, and only be marked shutdown function-unsafe if a problem
+	* is discovered.
+	*
+	* @return bool		Whether the cron task is shutdown function-safe.
 	*/
 	public function is_shutdown_function_safe()
 	{
diff --git a/phpBB/includes/cron/task/core/prune_all_forums.php b/phpBB/includes/cron/task/core/prune_all_forums.php
index 69ae7f63cd..39b5765229 100644
--- a/phpBB/includes/cron/task/core/prune_all_forums.php
+++ b/phpBB/includes/cron/task/core/prune_all_forums.php
@@ -63,6 +63,8 @@ class phpbb_cron_task_core_prune_all_forums extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* This cron task will only run when system cron is utilised.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
diff --git a/phpBB/includes/cron/task/core/prune_forum.php b/phpBB/includes/cron/task/core/prune_forum.php
index 18db44cf2d..55b1c58cd4 100644
--- a/phpBB/includes/cron/task/core/prune_forum.php
+++ b/phpBB/includes/cron/task/core/prune_forum.php
@@ -38,7 +38,7 @@ class phpbb_cron_task_core_prune_forum extends phpbb_cron_task_base implements p
 	* and a database query will be performed to load the necessary information
 	* about the forum.
 	*
-	* @return void
+	* @param array $forum_data Information about a forum to be pruned.
 	*/
 	public function __construct($forum_data = null)
 	{
@@ -80,6 +80,12 @@ class phpbb_cron_task_core_prune_forum extends phpbb_cron_task_base implements p
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* This cron task will not run when system cron is utilised, as in
+	* such cases prune_all_forums task would run instead.
+	*
+	* Additionally, this task must be given the forum data, either via
+	* the constructor or parse_parameters method.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
@@ -92,6 +98,8 @@ class phpbb_cron_task_core_prune_forum extends phpbb_cron_task_base implements p
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* Forum pruning interval is specified in the forum data.
+	*
 	* @return bool
 	*/
 	public function should_run()
@@ -116,6 +124,8 @@ class phpbb_cron_task_core_prune_forum extends phpbb_cron_task_base implements p
 	*
 	* It is expected to have a key f whose value is id of the forum to be pruned.
 	*
+	* @param phpbb_request_interface $request Request object.
+	*
 	* @return void
 	*/
 	public function parse_parameters(phpbb_request_interface $request)
diff --git a/phpBB/includes/cron/task/core/queue.php b/phpBB/includes/cron/task/core/queue.php
index ccea4b85bd..0e9de05984 100644
--- a/phpBB/includes/cron/task/core/queue.php
+++ b/phpBB/includes/cron/task/core/queue.php
@@ -41,6 +41,8 @@ class phpbb_cron_task_core_queue extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* Queue task is only run if the email queue (file) exists.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
@@ -53,6 +55,8 @@ class phpbb_cron_task_core_queue extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between queue runs is specified in board configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
@@ -64,6 +68,11 @@ class phpbb_cron_task_core_queue extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can be run in shutdown function.
 	*
+	* A user reported that using the mail() function during shutdown
+	* function execution does not work. Therefore if email is delivered
+	* via the mail() function (as opposed to SMTP) queue cron task marks
+	* itself shutdown function-unsafe.
+	*
 	* @return bool
 	*/
 	public function is_shutdown_function_safe()
diff --git a/phpBB/includes/cron/task/core/tidy_cache.php b/phpBB/includes/cron/task/core/tidy_cache.php
index 83a60d8760..793ce746b4 100644
--- a/phpBB/includes/cron/task/core/tidy_cache.php
+++ b/phpBB/includes/cron/task/core/tidy_cache.php
@@ -36,6 +36,9 @@ class phpbb_cron_task_core_tidy_cache extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* Tidy cache cron task runs if the cache implementation in use
+	* supports tidying.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
@@ -48,6 +51,9 @@ class phpbb_cron_task_core_tidy_cache extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between cache tidying is specified in board
+	* configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
diff --git a/phpBB/includes/cron/task/core/tidy_database.php b/phpBB/includes/cron/task/core/tidy_database.php
index 82a0a4583e..fb0e81eaba 100644
--- a/phpBB/includes/cron/task/core/tidy_database.php
+++ b/phpBB/includes/cron/task/core/tidy_database.php
@@ -41,6 +41,9 @@ class phpbb_cron_task_core_tidy_database extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between database tidying is specified in board
+	* configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
diff --git a/phpBB/includes/cron/task/core/tidy_search.php b/phpBB/includes/cron/task/core/tidy_search.php
index a781005960..dcc78abbb8 100644
--- a/phpBB/includes/cron/task/core/tidy_search.php
+++ b/phpBB/includes/cron/task/core/tidy_search.php
@@ -54,6 +54,10 @@ class phpbb_cron_task_core_tidy_search extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* Search cron task is runnable in all normal use. It may not be
+	* runnable if the search backend implementation selected in board
+	* configuration does not exist.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
@@ -70,6 +74,9 @@ class phpbb_cron_task_core_tidy_search extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between search tidying is specified in board
+	* configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
diff --git a/phpBB/includes/cron/task/core/tidy_sessions.php b/phpBB/includes/cron/task/core/tidy_sessions.php
index 5826584691..81e7e6a147 100644
--- a/phpBB/includes/cron/task/core/tidy_sessions.php
+++ b/phpBB/includes/cron/task/core/tidy_sessions.php
@@ -37,6 +37,9 @@ class phpbb_cron_task_core_tidy_sessions extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between session tidying is specified in board
+	* configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
diff --git a/phpBB/includes/cron/task/core/tidy_warnings.php b/phpBB/includes/cron/task/core/tidy_warnings.php
index 3b0cf57f0c..e7d4cc9eea 100644
--- a/phpBB/includes/cron/task/core/tidy_warnings.php
+++ b/phpBB/includes/cron/task/core/tidy_warnings.php
@@ -42,6 +42,8 @@ class phpbb_cron_task_core_tidy_warnings extends phpbb_cron_task_base
 	/**
 	* Returns whether this cron task can run, given current board configuration.
 	*
+	* If warnings are set to never expire, this cron task will not run.
+	*
 	* @return bool
 	*/
 	public function is_runnable()
@@ -54,6 +56,9 @@ class phpbb_cron_task_core_tidy_warnings extends phpbb_cron_task_base
 	* Returns whether this cron task should run now, because enough time
 	* has passed since it was last run.
 	*
+	* The interval between warnings tidying is specified in board
+	* configuration.
+	*
 	* @return bool
 	*/
 	public function should_run()
diff --git a/phpBB/includes/cron/task/parametrized.php b/phpBB/includes/cron/task/parametrized.php
index 6f87e1c818..c6c45be0c0 100644
--- a/phpBB/includes/cron/task/parametrized.php
+++ b/phpBB/includes/cron/task/parametrized.php
@@ -44,7 +44,9 @@ interface phpbb_cron_task_parametrized extends phpbb_cron_task
 	* $request contains user input and must not be trusted.
 	* Cron task must validate all data before using it.
 	*
+	* @param phpbb_request_interface $request Request object.
+	*
 	* @return void
 	*/
 	public function parse_parameters(phpbb_request_interface $request);
-}
-\ No newline at end of file
+}
diff --git a/phpBB/includes/cron/task/task.php b/phpBB/includes/cron/task/task.php
index 72fda91dd0..58c4a96f8e 100644
--- a/phpBB/includes/cron/task/task.php
+++ b/phpBB/includes/cron/task/task.php
@@ -49,6 +49,15 @@ interface phpbb_cron_task
 	/**
 	* Returns whether this cron task can be run in shutdown function.
 	*
+	* By the time shutdown sequence invokes a particular piece of code,
+	* resources that that code requires may already be released.
+	* If so, a particular cron task may be marked shutdown function-
+	* unsafe, and it will be executed in normal program flow.
+	*
+	* Generally speaking cron tasks should start off as shutdown function-
+	* safe, and only be marked shutdown function-unsafe if a problem
+	* is discovered.
+	*
 	* @return bool
 	*/
 	public function is_shutdown_function_safe();
diff --git a/phpBB/includes/cron/task/wrapper.php b/phpBB/includes/cron/task/wrapper.php
index 23cd4de724..238d97853c 100644
--- a/phpBB/includes/cron/task/wrapper.php
+++ b/phpBB/includes/cron/task/wrapper.php
@@ -24,9 +24,11 @@ if (!defined('IN_PHPBB'))
 class phpbb_cron_task_wrapper
 {
 	/**
+	* Constructor.
+	*
 	* Wraps a task $task, which must implement cron_task interface.
 	*
-	* @return void
+	* @param phpbb_cron_task $task The cron task to wrap.
 	*/
 	public function __construct(phpbb_cron_task $task)
 	{
@@ -34,7 +36,7 @@ class phpbb_cron_task_wrapper
 	}
 
 	/**
-	* Returns whether this task is parametrized.
+	* Returns whether the wrapped task is parametrised.
 	*
 	* Parametrized tasks accept parameters during initialization and must
 	* normally be scheduled with parameters.
@@ -72,7 +74,11 @@ class phpbb_cron_task_wrapper
 	/**
 	* Returns a url through which this task may be invoked via web.
 	*
-	* @return string		URL
+	* When system cron is not in use, running a cron task is accomplished
+	* by outputting an image with the url returned by this function as
+	* source.
+	*
+	* @return string		URL through which this task may be invoked.
 	*/
 	public function get_url()
 	{