some minor cleanups in subscription.php

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