[feature/system-cron] Added @param/@return documentation

Also adjusted some function descriptions for greater informativity.

PHPBB3-9596

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()

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)

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()

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()

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()

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()

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()

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()