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

Also adjusted some function descriptions for greater informativity.

PHPBB3-9596

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.
 	*
-	* Attempting to release a cron lock that is already released is harmless.
+	* The lock must have been previously obtained, that is, lock() call
+	* was issued and returned true.
+	*
+	* Note: Attempting to release a cron lock that is already released,
+	* that is, calling unlock() multiple times, is harmless.
 	*
 	* @return void
 	*/

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

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

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

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);
-}
+}

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

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