12 files changed, 77 insertions, 6 deletions
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()
 	{