[ticket/10073] Add doc blocks to new classes

PHPBB3-10073

phpBB/phpbb/message/admin_form.php

@@ -9,12 +9,24 @@
 
 namespace phpbb\message;
 
+/**
+* Class admin_form
+* Displays a message to the user and allows him to send an email
+*
+* @package phpbb\message
+*/
 class admin_form extends form
 {
+	/** @var string */
 	protected $subject;
+	/** @var string */
 	protected $sender_name;
+	/** @var string */
 	protected $sender_address;
 
+	/**
+	* {inheritDoc}
+	*/
 	public function check_allow()
 	{
 		$error = parent::check_allow();
@@ -31,6 +43,9 @@ class admin_form extends form
 		return false;
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function bind(\phpbb\request\request_interface $request)
 	{
 		parent::bind($request);
@@ -40,6 +55,9 @@ class admin_form extends form
 		$this->sender_name = $request->variable('name', '', true);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function submit(\messenger $messenger)
 	{
 		if (!$this->subject)
@@ -93,6 +111,9 @@ class admin_form extends form
 		parent::submit($messenger);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function render(\phpbb\template\template $template)
 	{
 		$template->assign_vars(array(

phpBB/phpbb/message/form.php

@@ -9,6 +9,11 @@
 
 namespace phpbb\message;
 
+/**
+* Abstract class form
+*
+* @package phpbb\message
+*/
 abstract class form
 {
 	/** @var \phpbb\auth\auth */
@@ -17,6 +22,8 @@ abstract class form
 	protected $config;
 	/** @var \phpbb\db\driver\driver_interface */
 	protected $db;
+	/** @var \phpbb\message\message */
+	protected $message;
 	/** @var \phpbb\user */
 	protected $user;
 
@@ -25,11 +32,23 @@ abstract class form
 	/** @var string */
 	protected $phpEx;
 
-	protected $errors;
+	/** @var array */
-	protected $message;
+	protected $errors = array();
+	/** @var bool */
 	protected $cc_sender;
+	/** @var string */
 	protected $body;
 
+	/**
+	* Construct
+	*
+	* @param \phpbb\auth\auth $auth
+	* @param \phpbb\config\config $config
+	* @param \phpbb\db\driver\driver_interface $db
+	* @param \phpbb\user $user
+	* @param string $phpbb_root_path
+	* @param string $phpEx
+	*/
 	public function __construct(\phpbb\auth\auth $auth, \phpbb\config\config $config, \phpbb\db\driver\driver_interface $db, \phpbb\user $user, $phpbb_root_path, $phpEx)
 	{
 		$this->phpbb_root_path = $phpbb_root_path;
@@ -39,25 +58,35 @@ abstract class form
 		$this->config = $config;
 		$this->db = $db;
 
-		$this->errors = array();
+		$this->message = new message($config['server_name']);
-
-		$this->message = new \phpbb\message\message($config['server_name']);
 		$this->message->set_sender_from_user($this->user);
 	}
 
 	/**
 	* Returns the title for the email form page
+	*
+	* @return string
 	*/
 	public function get_page_title()
 	{
-		$this->user->lang['SEND_EMAIL'];
+		return $this->user->lang['SEND_EMAIL'];
 	}
 
+	/**
+	* Returns the file name of the form template
+	*
+	* @return string
+	*/
 	public function get_template_file()
 	{
 		return 'memberlist_email.html';
 	}
 
+	/**
+	* Checks whether the user is allowed to use the form
+	*
+	* @return false|string	Error string if not allowed, false otherwise
+	*/
 	public function check_allow()
 	{
 		if (!$this->config['email_enable'])
@@ -73,17 +102,34 @@ abstract class form
 		return false;
 	}
 
+	/**
+	* Get the return link after the message has been sent
+	*
+	* @return string
+	*/
 	public function get_return_message()
 	{
 		return sprintf($this->user->lang['RETURN_INDEX'], '<a href="' . append_sid($this->phpbb_root_path . 'index.' . $this->phpEx) . '">', '</a>');
 	}
 
+	/**
+	* Bind the values of the request to the form
+	*
+	* @param \phpbb\request\request_interface $request
+	* @return null
+	*/
 	public function bind(\phpbb\request\request_interface $request)
 	{
 		$this->cc_sender = $request->is_set_post('cc_sender');
 		$this->body = $request->variable('message', '', true);
 	}
 
+	/**
+	* Submit form, generate the email and send it
+	*
+	* @param \messenger $messenger
+	* @return null
+	*/
 	public function submit(\messenger $messenger)
 	{
 		if (!check_form_key('memberlist_email'))
@@ -110,6 +156,12 @@ abstract class form
 		}
 	}
 
+	/**
+	* Render the template of the form
+	*
+	* @param \phpbb\template\template $template
+	* @return null
+	*/
 	public function render(\phpbb\template\template $template)
 	{
 		add_form_key('memberlist_email');

phpBB/phpbb/message/message.php

@@ -9,63 +9,129 @@
 
 namespace phpbb\message;
 
+/**
+* Class message
+* Holds all information for an email and sends it in the end
+*
+* @package phpbb\message
+*/
 class message
 {
+	/** @var string */
 	protected $server_name;
 
+	/** @var string */
 	protected $subject = '';
+	/** @var string */
 	protected $body = '';
+	/** @var string */
 	protected $template = '';
+	/** @var array */
 	protected $template_vars = array();
 
+	/** @var string */
 	protected $sender_ip = '';
+	/** @var string */
 	protected $sender_name = '';
+	/** @var string */
 	protected $sender_address = '';
+	/** @var string */
 	protected $sender_lang = '';
+	/** @var string */
 	protected $sender_id = '';
+	/** @var string */
 	protected $sender_username = '';
+	/** @var string */
 	protected $sender_jabber = '';
+	/** @var int */
 	protected $sender_notify_type = NOTIFY_EMAIL;
 
+	/** @var array */
 	protected $recipients;
 
+	/**
+	* Construct
+	*
+	* @param string $server_name	Used for AntiAbuse header
+	*/
 	public function __construct($server_name)
 	{
 		$this->server_name = $server_name;
 	}
 
+	/**
+	* Set the subject of the email
+	*
+	* @param string $subject
+	* @return null
+	*/
 	public function set_subject($subject)
 	{
 		$this->subject = $subject;
 	}
 
+	/**
+	* Set the body of the email text
+	*
+	* @param string $body
+	* @return null
+	*/
 	public function set_body($body)
 	{
 		$this->body = $body;
 	}
 
+	/**
+	* Set the name of the email template to use
+	*
+	* @param string $template
+	* @return null
+	*/
 	public function set_template($template)
 	{
 		$this->template = $template;
 	}
 
+	/**
+	* Set the array with the "template" data for the email
+	*
+	* @param array $template_vars
+	* @return null
+	*/
 	public function set_template_vars($template_vars)
 	{
 		$this->template_vars = $template_vars;
 	}
 
+	/**
+	* Add a recipient from \phpbb\user
+	*
+	* @param \phpbb\user $user
+	* @return null
+	*/
 	public function add_recipient_from_user_row(array $user)
 	{
 		$this->add_recipient(
 			$user['username'],
 			$user['user_email'],
 			$user['user_lang'],
+			$user['user_notify_type'],
 			$user['username'],
-			$user['user_jabber'],
+			$user['user_jabber']
-			$user['user_notify_type']
 		);
 	}
 
+	/**
+	* Add a recipient
+	*
+	* @param string $recipient_name		Displayed sender name
+	* @param string $recipient_address	Email address
+	* @param string $recipient_lang
+	* @param int $recipient_notify_type	Used notification methods (Jabber, Email, ...)
+	* @param string $recipient_username	User Name (used for AntiAbuse header)
+	* @param string $recipient_jabber
+	* @return null
+	*/
 	public function add_recipient($recipient_name, $recipient_address, $recipient_lang, $recipient_notify_type = NOTIFY_EMAIL, $recipient_username = '', $recipient_jabber = '')
 	{
 		$this->recipients[] = array(
@@ -79,6 +145,12 @@ class message
 		);
 	}
 
+	/**
+	* Set the senders data from \phpbb\user object
+	*
+	* @param \phpbb\user $user
+	* @return null
+	*/
 	public function set_sender_from_user($user)
 	{
 		$this->set_sender(
@@ -94,6 +166,18 @@ class message
 		$this->set_sender_notify_type($user->data['user_notify_type']);
 	}
 
+	/**
+	* Set the senders data
+	*
+	* @param string $sender_ip
+	* @param string $sender_name		Displayed sender name
+	* @param string $sender_address		Email address
+	* @param string $sender_lang
+	* @param int $sender_id				User ID
+	* @param string $sender_username	User Name (used for AntiAbuse header)
+	* @param string $sender_jabber
+	* @return null
+	*/
 	public function set_sender($sender_ip, $sender_name, $sender_address, $sender_lang = '', $sender_id = 0, $sender_username = '', $sender_jabber = '')
 	{
 		$this->sender_ip = $sender_ip;
@@ -105,6 +189,12 @@ class message
 		$this->sender_jabber = $sender_jabber;
 	}
 
+	/**
+	* Which notification type should be used? Jabber, Email, ...?
+	*
+	* @param int $sender_notify_type
+	* @return null
+	*/
 	public function set_sender_notify_type($sender_notify_type)
 	{
 		$this->sender_notify_type = $sender_notify_type;
@@ -137,6 +227,13 @@ class message
 		);
 	}
 
+	/**
+	* Send the email
+	*
+	* @param \messenger $messenger
+	* @param string $phpEx
+	* @return null
+	*/
 	public function send(\messenger $messenger, $phpEx)
 	{
 		if (!sizeof($this->recipients))

phpBB/phpbb/message/topic_form.php

@@ -9,15 +9,31 @@
 
 namespace phpbb\message;
 
+/**
+* Class topic_form
+* Form used to send topics as notification emails
+*
+* @package phpbb\message
+*/
 class topic_form extends form
 {
+	/** @var int */
 	protected $topic_id;
-
+	/** @var array */
 	protected $topic_row;
+	/** @var string */
 	protected $recipient_address;
+	/** @var string */
 	protected $recipient_name;
+	/** @var string */
 	protected $recipient_lang;
 
+	/**
+	* Get the data of the topic
+	*
+	* @param int $topic_id
+	* @return	false|array		false if the topic does not exist, array otherwise
+	*/
 	protected function get_topic_row($topic_id)
 	{
 		$sql = 'SELECT forum_id, topic_title
@@ -30,6 +46,9 @@ class topic_form extends form
 		return $row;
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function check_allow()
 	{
 		$error = parent::check_allow();
@@ -61,6 +80,9 @@ class topic_form extends form
 		return false;
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function bind(\phpbb\request\request_interface $request)
 	{
 		parent::bind($request);
@@ -73,6 +95,9 @@ class topic_form extends form
 		$this->topic_row = $this->get_topic_row($this->topic_id);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function submit(\messenger $messenger)
 	{
 		if (!$this->recipient_address || !preg_match('/^' . get_preg_expression('email') . '$/i', $this->recipient_address))
@@ -102,11 +127,17 @@ class topic_form extends form
 		parent::submit($messenger);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function get_return_message()
 	{
 		return sprintf($this->user->lang['RETURN_TOPIC'],  '<a href="' . append_sid($this->phpbb_root_path . 'viewtopic.' . $this->phpEx, 'f=' . $this->topic_row['forum_id'] . '&amp;t=' . $this->topic_id) . '">', '</a>');
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function render(\phpbb\template\template $template)
 	{
 		parent::render($template);

phpBB/phpbb/message/user_form.php

@@ -9,12 +9,43 @@
 
 namespace phpbb\message;
 
+/**
+* Class user_form
+* Allows users to send emails to other users
+*
+* @package phpbb\message
+*/
 class user_form extends form
 {
+	/** @var int */
 	protected $recipient_id;
-	protected $subject;
+	/** @var array */
 	protected $recipient_row;
+	/** @var string */
+	protected $subject;
 
+	/**
+	* Get the data of the recipient
+	*
+	* @param int $user_id
+	* @return	false|array		false if the user does not exist, array otherwise
+	*/
+	protected function get_user_row($user_id)
+	{
+		$sql = 'SELECT username, user_email, user_allow_viewemail, user_lang, user_jabber, user_notify_type
+			FROM ' . USERS_TABLE . '
+			WHERE user_id = ' . (int) $user_id . '
+				AND user_type IN (' . USER_NORMAL . ', ' . USER_FOUNDER . ')';
+		$result = $this->db->sql_query($sql);
+		$row = $this->db->sql_fetchrow($result);
+		$this->db->sql_freeresult($result);
+
+		return $row;
+	}
+
+	/**
+	* {inheritDoc}
+	*/
 	public function check_allow()
 	{
 		$error = parent::check_allow();
@@ -47,19 +78,9 @@ class user_form extends form
 		return false;
 	}
 
-	protected function get_user_row($user_id)
+	/**
-	{
+	* {inheritDoc}
-		$sql = 'SELECT username, user_email, user_allow_viewemail, user_lang, user_jabber, user_notify_type
+	*/
-			FROM ' . USERS_TABLE . '
-			WHERE user_id = ' . ((int) $user_id) . '
-				AND user_type IN (' . USER_NORMAL . ', ' . USER_FOUNDER . ')';
-		$result = $this->db->sql_query($sql);
-		$row = $this->db->sql_fetchrow($result);
-		$this->db->sql_freeresult($result);
-
-		return $row;
-	}
-
 	public function bind(\phpbb\request\request_interface $request)
 	{
 		parent::bind($request);
@@ -70,6 +91,9 @@ class user_form extends form
 		$this->recipient_row = $this->get_user_row($this->recipient_id);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function submit(\messenger $messenger)
 	{
 		if (!$this->subject)
@@ -90,6 +114,9 @@ class user_form extends form
 		parent::submit($messenger);
 	}
 
+	/**
+	* {inheritDoc}
+	*/
 	public function render(\phpbb\template\template $template)
 	{
 		parent::render($template);