From c0ec69288a7ae838ba9f3da6cc5069d6abe33e15 Mon Sep 17 00:00:00 2001
From: Andreas Gohr <andi@splitbrain.org>
Date: Sat, 11 Aug 2012 22:38:19 +0200
Subject: [PATCH] some minor cleanups in subscription.php
---
inc/subscription.php | 60 +++++++++++++++++++++++++++-----------------
1 file changed, 37 insertions(+), 23 deletions(-)
diff --git a/inc/subscription.php b/inc/subscription.php
index d1ee0397a..1f1aedfa4 100644
--- a/inc/subscription.php
+++ b/inc/subscription.php
@@ -20,10 +20,11 @@
* Get the name of the metafile tracking subscriptions to target page or
* namespace
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param string $id The target page or namespace, specified by id; Namespaces
* are identified by appending a colon.
- *
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return string
*/
function subscription_filename($id) {
$meta_fname = '.mlist';
@@ -39,16 +40,23 @@ function subscription_filename($id) {
/**
* Lock subscription info for an ID
*
+ * @author Adrian Lang <lang@cosmocode.de>
* @param string $id The target page or namespace, specified by id; Namespaces
* are identified by appending a colon.
- *
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return string
*/
function subscription_lock_filename ($id){
global $conf;
return $conf['lockdir'].'/_subscr_' . md5($id) . '.lock';
}
+/**
+ * Creates a lock file for writing subscription data
+ *
+ * @todo add lock time parameter to io_lock() and use this instead
+ * @param $id
+ * @return bool
+ */
function subscription_lock($id) {
global $conf;
$lock = subscription_lock_filename($id);
@@ -70,10 +78,10 @@ function subscription_lock($id) {
/**
* Unlock subscription info for an ID
*
+ * @author Adrian Lang <lang@cosmocode.de>
* @param string $id The target page or namespace, specified by id; Namespaces
* are identified by appending a colon.
- *
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return bool
*/
function subscription_unlock($id) {
$lockf = subscription_lock_filename($id);
@@ -92,6 +100,8 @@ function subscription_unlock($id) {
* returned if a subscription should be deleted but the user is not subscribed
* and the subscription meta file exists.
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param string $user The subscriber or unsubscriber
* @param string $page The target object (page or namespace), specified by
* id; Namespaces are identified by a trailing colon.
@@ -99,8 +109,7 @@ function subscription_unlock($id) {
* “everyâ€, “digestâ€, and “listâ€.
* @param string $data An optional data blob
* @param bool $overwrite Whether an existing subscription may be overwritten
- *
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return bool
*/
function subscription_set($user, $page, $style, $data = null,
$overwrite = false) {
@@ -149,12 +158,12 @@ function subscription_set($user, $page, $style, $data = null,
* This function searches all relevant subscription files for a page or
* namespace.
*
- * @param string $page The target object’s (namespace or page) id
- * @param array $pre A hash of predefined values
- *
+ * @author Adrian Lang <lang@cosmocode.de>
* @see function subscription_regex for $pre documentation
*
- * @author Adrian Lang <lang@cosmocode.de>
+ * @param string $page The target object’s (namespace or page) id
+ * @param array $pre A hash of predefined values
+ * @return array
*/
function subscription_find($page, $pre) {
// Construct list of files which may contain relevant subscriptions.
@@ -231,13 +240,15 @@ function get_info_subscribed() {
/**
* Construct a regular expression parsing a subscription definition line
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param array $pre A hash of predefined values; “userâ€, “styleâ€, and
* “data†may be set to limit the results to
* subscriptions matching these parameters. If
* “escaped†is true, these fields are inserted into the
* regular expression without escaping.
*
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return string complete regexp including delimiters
*/
function subscription_regex($pre = array()) {
if (!isset($pre['escaped']) || $pre['escaped'] === false) {
@@ -258,15 +269,18 @@ function subscription_regex($pre = array()) {
*
* This is the default action for COMMON_NOTIFY_ADDRESSLIST.
*
+ * @author Steven Danz <steven-danz@kc.rr.com>
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @todo this does NOT return a string but uses a reference to write back, either fix function or docs
* @param array $data Containing $id (the page id), $self (whether the author
* should be notified, $addresslist (current email address
* list)
- *
- * @author Steven Danz <steven-danz@kc.rr.com>
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return string
*/
function subscription_addresslist(&$data){
global $conf;
+ /** @var auth_basic $auth */
global $auth;
$id = $data['id'];
@@ -303,11 +317,11 @@ function subscription_addresslist(&$data){
*
* Sends a digest mail showing a bunch of changes.
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param string $subscriber_mail The target mail address
* @param array $id The ID
* @param int $lastupdate Time of the last notification
- *
- * @author Adrian Lang <lang@cosmocode.de>
*/
function subscription_send_digest($subscriber_mail, $id, $lastupdate) {
$n = 0;
@@ -339,11 +353,11 @@ function subscription_send_digest($subscriber_mail, $id, $lastupdate) {
*
* Sends a list mail showing a list of changed pages.
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param string $subscriber_mail The target mail address
* @param array $ids Array of ids
* @param string $ns_id The id of the namespace
- *
- * @author Adrian Lang <lang@cosmocode.de>
*/
function subscription_send_list($subscriber_mail, $ids, $ns_id) {
if (count($ids) === 0) return;
@@ -365,6 +379,8 @@ function subscription_send_list($subscriber_mail, $ids, $ns_id) {
/**
* Helper function for sending a mail
*
+ * @author Adrian Lang <lang@cosmocode.de>
+ *
* @param string $subscriber_mail The target mail address
* @param array $replaces Predefined parameters used to parse the
* template
@@ -372,11 +388,9 @@ function subscription_send_list($subscriber_mail, $ids, $ns_id) {
* prefix “mail_â€)
* @param string $id The page or namespace id
* @param string $template The name of the mail template
- *
- * @author Adrian Lang <lang@cosmocode.de>
+ * @return bool
*/
function subscription_send($subscriber_mail, $replaces, $subject, $id, $template) {
- global $conf;
global $lang;
$text = rawLocale($template);
--
GitLab