From 0a9d45a4b762625179fcc66403b78637c4bfdb71 Mon Sep 17 00:00:00 2001
From: Jordan Halterman <jordan.halterman@gmail.com>
Date: Mon, 20 Feb 2012 19:08:20 -0800
Subject: [PATCH] Issue #1447598: Add data types to param/return
 documentation.

---
 includes/admin.settings.inc   |   10 ++-
 includes/broadcast.inc        |   18 +++---
 includes/date.inc             |   17 ++---
 includes/event.6x-2.inc       |    4 +-
 includes/node_form.inc        |    7 +--
 includes/node_output.inc      |   10 ++--
 includes/node_settings.inc    |   14 ++--
 includes/scheduler.inc        |    8 +-
 includes/signup_edit_form.inc |   14 ++--
 includes/signup_form.inc      |   29 +++++----
 includes/token_help.inc       |    4 +-
 signup.api.php                |   41 +++++-------
 signup.module                 |  145 +++++++++++++++++++++++------------------
 theme/admin.inc               |    4 +-
 theme/email.inc               |   25 ++++---
 theme/node.admin.inc          |    6 +-
 theme/node.inc                |   12 ++--
 theme/signup_form.inc         |    8 +-
 18 files changed, 193 insertions(+), 183 deletions(-)

diff --git a/includes/admin.settings.inc b/includes/admin.settings.inc
index be214df..4ca9f9c 100644
--- a/includes/admin.settings.inc
+++ b/includes/admin.settings.inc
@@ -188,8 +188,10 @@ function signup_settings_form($form, &$form_state) {
 /**
  * Submits the signup settings form
  *
- * @param $form_id The ID of the form being submitted.
- * @param $form_values The constructed form values array of the submitted form.
+ * @param string $form_id
+ *   The ID of the form being submitted.
+ * @param array $form_values
+ *   The constructed form values array of the submitted form.
  */
 function signup_settings_form_submit($form, &$form_state) {
   $op = isset($form_state['values']['op']) ? $form_state['values']['op'] : '';
@@ -243,12 +245,12 @@ function signup_settings_form_submit($form, &$form_state) {
 /**
  * Generates the appropriate selector label for a given view.
  *
- * @param $view
+ * @param views_view $view
  *   An object containing data about the view to generate a label for.
  *   Contains at least a name (string), description (string), page
  *   (bool), and block (bool) fields.
  *
- * @return
+ * @return string
  *   The plain text (no HTML allowed) to include as the label for this view in
  *   the drop-down selector for which view to embed on the site-wide signup
  *   settings page.
diff --git a/includes/broadcast.inc b/includes/broadcast.inc
index e703467..ed4909e 100644
--- a/includes/broadcast.inc
+++ b/includes/broadcast.inc
@@ -7,7 +7,7 @@
 /**
  * Form builder for the signup broadcast form.
  *
- * @param $node
+ * @param stdClass $node
  *   The node that the broadcast form is being attached to.
  */
 function signup_broadcast_form($form, $form_state, $node) {
@@ -88,9 +88,9 @@ function signup_broadcast_form($form, $form_state, $node) {
 /**
  * Submit callback for the signup broadcast form.
  *
- * @param $form
+ * @param array $form
  *   The broadcast form being submitted.
- * @param $form_state
+ * @param array $form_state
  *   The state of the submitted form (including values).
  *
  * @see signup_send_broadcast()
@@ -109,17 +109,17 @@ function signup_broadcast_form_submit($form, &$form_state) {
 /**
  * Send an email message to users who have signed up to a node.
  *
- * @param $nid
+ * @param int $nid
  *   Node ID of the signup node to send a broadcast about.
- * @param $subject
+ * @param string $subject
  *   The subject of the broadcast message to send.
- * @param $body
+ * @param string $body
  *   The body of the broadcast message to send.
- * @param $from
+ * @param string $from
  *   The from address to use when sending the broadcast message.
- * @param $copy
+ * @param bool $copy
  *   Optional boolean indicating if the current user should get a copy.
- * @param $signups
+ * @param array $signups
  *   Optional array of signup objects to send the broadcast to.  Each object
  *   in the array should at least contain the following fields:
  *   - "sid": The unique signup ID
diff --git a/includes/date.inc b/includes/date.inc
index 4d8079d..d4e6389 100644
--- a/includes/date.inc
+++ b/includes/date.inc
@@ -195,10 +195,10 @@ function _signup_date_alter_node_type_form(&$form, &$form_state) {
 /**
  * Create the FAPI form element for the signup date field.
  *
- * @param $type
+ * @param string $type
  *   The node type to generate the form element for.
  *
- * @return
+ * @return array
  *   FAPI form array for the signup date field element.
  *
  * @see _signup_date_field_form_alter()
@@ -221,7 +221,7 @@ function _signup_date_field_element($type) {
  * configuration of any signup-enabled node types to ensure that the CCK date
  * field and signup settings make sense.
  *
- * @param $type
+ * @param string $type
  *   The 4th element in the URL which specifies which node type is currently
  *   being configured.  If this is empty, it means we're at the node type
  *   overview listing and we should test all node types.
@@ -251,14 +251,11 @@ function signup_date_check_node_types($type = NULL) {
  * date fields at all, or if they have date fields but haven't selected the
  * one to use for signup functionality.
  *
- * @param $type
+ * @param string $type
  *   The node type to check signup and CCK date field configuration on.
- * @param $name
+ * @param string $name
  *   Human readable name of the node type to check.
  *
- * @return
- *   Nothing -- configuration errors are reported via drupal_set_message().
- *
  * @see signup_help()
  */
 function signup_date_field_check_config($type, $name) {
@@ -294,10 +291,10 @@ function signup_date_field_check_config($type, $name) {
 /**
  * Helper function for the date field select to build its options.
  *
- * @param $type
+ * @param string $type
  *   Content type whose date fields should be listed.
  *
- * @return
+ * @return array
  *   Associative array with all date fields of the given content type plus
  *   'None' and an optional 'Not specified' if the user never selected a
  *   value.
diff --git a/includes/event.6x-2.inc b/includes/event.6x-2.inc
index 2cb6649..dfe7b40 100644
--- a/includes/event.6x-2.inc
+++ b/includes/event.6x-2.inc
@@ -90,10 +90,10 @@ function _signup_event_format_date($node) {
 /**
  * Determine if the given node has a start time managed by the event.module.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully loaded node object to test.
  *
- * @return
+ * @return string
  *   'event' if this is an event node, otherwise 'none'.
  *
  * @see _signup_get_node_scheduler()
diff --git a/includes/node_form.inc b/includes/node_form.inc
index 47d8374..c85dfb1 100644
--- a/includes/node_form.inc
+++ b/includes/node_form.inc
@@ -20,14 +20,11 @@
  * properly signup-enabled (these settings can be changed by visiting the
  * "Settings" subtab under the "Signups" tab at node/N/signups/settings).
  *
- * @param $node
+ * @param stdClass $node
  *   The node object given to signup_nodeapi().
- * @param $op
+ * @param string $op
  *   The hook_nodeapi() operation, either 'insert' or 'update'.
  *
- * @return
- *   Nothing, this function is expected to update the database.
- *
  * @see signup_nodeapi()
  */
 function signup_save_node($node, $op) {
diff --git a/includes/node_output.inc b/includes/node_output.inc
index 4a722ef..4cb4138 100644
--- a/includes/node_output.inc
+++ b/includes/node_output.inc
@@ -11,12 +11,12 @@
  * appear at the bottom of the node or on a separate tab, this function is
  * shared by multiple callers.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully loaded node object.
- * @param $type
+ * @param string $type
  *   The kind of output would we render: can be either 'node' or 'tab'.
  *
- * @return
+ * @return string
  *   The fully rendered HTML for all signup-related forms and info.
  *
  * @see signup_nodeapi()
@@ -145,10 +145,10 @@ function signup_user_list_output($node) {
  * output to appear on a separate tab, instead of directly embedded in the
  * node.
  *
- * @param $node
+ * @param stdClass $node
  *   The node to generate a signup tab for.
  *
- * @return
+ * @return string
  *   The contents of the signup tab.
  *
  * @see _signup_node_output()
diff --git a/includes/node_settings.inc b/includes/node_settings.inc
index 7efbee4..643f565 100644
--- a/includes/node_settings.inc
+++ b/includes/node_settings.inc
@@ -9,19 +9,19 @@
  *
  * This is shared by the settings page and the node edit page.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully loaded node object if we've got it.
- * @param $node_type
+ * @param string $node_type
  *   The type of the node.  When creating new content, the caller can know the
  *   node type, even if $node is NULL.
- * @param $has_date
+ * @param bool $has_date
  *   Boolean flag indicating if this node (or site) has signup-aware
  *   date functionality, which is required for reminder emails to be in
  *   the form.
- * @param $include_buttons
+ * @param bool $include_buttons
  *   Boolean flag indicating if the form should include its own submit buttons.
  *
- * @return
+ * @return array
  *   The form array for the per-node signup settings.
  *
  */
@@ -158,9 +158,9 @@ function signup_node_settings_page($node) {
 /**
  * Submit handler for the per-node signup settings form.
  *
- * @param $form_id
+ * @param string $form_id
  *   The ID of the form being submitted.
- * @param $form_values
+ * @param array $form_values
  *   The constructed form values array of the submitted form.
  */
 function signup_node_settings_form_submit($form, &$form_state) {
diff --git a/includes/scheduler.inc b/includes/scheduler.inc
index bbf0356..aa487d2 100644
--- a/includes/scheduler.inc
+++ b/includes/scheduler.inc
@@ -29,10 +29,10 @@ function signup_site_has_dates() {
 /**
  * Determine which scheduler backend to use for the given node.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully loaded node object to test.
  *
- * @return
+ * @return string
  *   'event' to use the event.module, 'date' for the date.module, or 'none' if
  *   the node is untimed.
  *
@@ -56,10 +56,10 @@ function _signup_get_node_scheduler($node) {
 /**
  * Determine which scheduler backend to use for the given node type.
  *
- * @param $type
+ * @param string $type
  *   Machine-readable name of the node type to test.
  *
- * @return
+ * @return string
  *   'event' to use the event.module, 'date' for the date.module, or 'none' if
  *   the node type is untimed.
  */
diff --git a/includes/signup_edit_form.inc b/includes/signup_edit_form.inc
index 3a1eb47..d3213a8 100644
--- a/includes/signup_edit_form.inc
+++ b/includes/signup_edit_form.inc
@@ -7,16 +7,16 @@
 /**
  * Build the form for editing existing signups.
  *
- * @param $form
+ * @param array $form
  *   An associative array containing the structure of the form.
- * @param $form_state
+ * @param array $form_state
  *   The state of the form to build (not currently used).
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object with data about the signup to edit.
- * @param $type
+ * @param string $type
  *   The type of signup edit form to render, can be 'node', 'tab', or 'admin'.
  *
- * @return
+ * @return array
  *   The FAPI form array for the signup edit form.
  */
 function signup_edit_form($form, &$form_state, $signup, $type) {
@@ -182,10 +182,10 @@ function signup_edit_form_save_submit($form, $form_state) {
 /**
  * Page handler for the administrator page to edit an existing signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object to edit.
  *
- * @return
+ * @return string
  *   The HTML to use for the signup edit page.
  */
 function signup_edit_page($signup) {
diff --git a/includes/signup_form.inc b/includes/signup_form.inc
index 79ae2c2..23b6b0d 100644
--- a/includes/signup_form.inc
+++ b/includes/signup_form.inc
@@ -7,15 +7,18 @@
 /**
  * Build the user signup form.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully loaded node object.
- * @param $signup_type
+ * @param string $signup_type
  *   Determines what kind of signup to generate a form for. Possible values:
  *    'auth' -- regular authenticated user signup form
  *    'anon' -- anonymous user signup form (includes required email field).
  *    'admin' -- admin form to signup another user (includes user selector).
- * @param $fieldset
+ * @param bool $fieldset
  *   Boolean that indicates if the signup form should be in a fieldset.
+ *
+ * @return array
+ *   An FAPI array defining the signup form.
  */
 function signup_form($form, &$form_state, $node, $signup_type = 'auth', $fieldset = TRUE) {
   global $user;
@@ -103,9 +106,9 @@ function signup_form($form, &$form_state, $node, $signup_type = 'auth', $fieldse
 /**
  * Submit handler for the user signup form.
  *
- * @param $form
+ * @param array $form
  *   The form being submitted.
- * @param $form_values
+ * @param array $form_values
  *   The state of the form, including the submitted values.
  */
 function signup_form_submit($form, &$form_state) {
@@ -121,9 +124,9 @@ function signup_form_submit($form, &$form_state) {
 /**
  * Validate handler for the email address on the anonymous user signup form.
  *
- * @param $form
+ * @param array $form
  *   Form array for the anonymous user email field.
- * @param $form_state
+ * @param array $form_state
  *   State of the form, including the submitted values to validate.
  */
 function signup_form_validate_anon($form, $form_state) {
@@ -135,11 +138,11 @@ function signup_form_validate_anon($form, $form_state) {
 /**
  * Validate the email address for an anonymous signup.
  *
- * @param $nid
+ * @param int $nid
  *   The node the user is signing up for.
- * @param $anon_mail
+ * @param string $anon_mail
  *   The anonymous email address to validate.
- * @param $name
+ * @param string|false $name
  *   The form element being validated (optional).
  *
  * @return Boolean.
@@ -175,10 +178,10 @@ function signup_validate_anon_email($nid, $anon_mail, $name = FALSE) {
 /**
  * Validates the username on the admin form to signup another user.
  *
- * @param $form
+ * @param array $form
  *   Form array for the username field.
- * @param $nid
- *   Node id of the node the user is being signed up for.
+ * @param array $form_state
+ *   The form state array containing node ID of the node the user is being signed up for.
  */
 function signup_form_validate_username($form, $form_state) {
   $nid = $form_state['values']['nid'];
diff --git a/includes/token_help.inc b/includes/token_help.inc
index ff8931d..a198962 100644
--- a/includes/token_help.inc
+++ b/includes/token_help.inc
@@ -7,9 +7,9 @@
 /**
  * Private function to generate HTML for showing the available tokens.
  *
- * @param $form
+ * @param array $form
  *   Reference to the form array to include the help fieldset in.
- * @param $element_name
+ * @param string $element_name
  *   Name of the form element to use for the help fieldset.
  */
 function _signup_token_help(&$form, $element_name) {
diff --git a/signup.api.php b/signup.api.php
index 88c263b..8d49559 100644
--- a/signup.api.php
+++ b/signup.api.php
@@ -7,9 +7,9 @@
 /**
  * Hook to alter signup data before a signup is inserted or updated.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Reference to the fully-loaded signup object representing the signup.
- * @param $form_values
+ * @param array $form_values
  *   Array of form values (if any) from the signup being inserted or updated.
  */
 function hook_signup_data_alter(&$signup, $form_values) {
@@ -23,17 +23,14 @@ function hook_signup_data_alter(&$signup, $form_values) {
  * {signup_log} table still exists, but the node has already had its signup
  * total decremented.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully-loaded node object that the signup is being canceled from.
- * @param $signup
+ * @param stdClass $signup
  *   An object containing all the known information about the signup being
  *   canceled. Contains all the data from the {signup_log} row representing
  *   the canceled signup. See the schema definition for descriptions of each
  *   field and what they represent.
  *
- * @return
- *   Ignored.
- *
  * @see signup_cancel_signup()
  */
 function hook_signup_cancel($signup, $node) {
@@ -54,7 +51,7 @@ function hook_signup_cancel($signup, $node) {
 /**
  * Hook invoked after a signup has been inserted.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object representing the new signup.
  */
 function hook_signup_insert($signup) {
@@ -64,7 +61,7 @@ function hook_signup_insert($signup) {
 /**
  * Hook invoked after a signup has been updated.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object representing the updated signup.
  */
 function hook_signup_update($signup) {
@@ -79,12 +76,12 @@ function hook_signup_update($signup) {
  * fields from theme_signup_user_form(), serialized, and stored in the
  * {signup_log} database table.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully-loaded node object being signed up to.
- * @param $account
+ * @param stdClass $account
  *   Full-loaded user object who is signing up.
  *
- * @return
+ * @return array
  *   Keyed array of fields to include in the custom data for this signup. The
  *   keys for the array are used as labels when displaying the field, so they
  *   should be human-readable (and wrapped in t() to allow translation).
@@ -107,12 +104,9 @@ function hook_signup_sign_up($node, $account) {
  * cancels a signup and the signup limit is no longer reached; 2) a signup
  * administrator manually re-opens signups.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully-loaded node object that is now open for signups.
  *
- * @return
- *   Ignored.
- *
  * @see signup_open_signup()
  */
 function hook_signup_open($node) {
@@ -128,12 +122,9 @@ function hook_signup_open($node) {
  * has a signup limit and the limit is reached; 3) a signup administrator
  * manually closes signups.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully-loaded node object that is now closed for signups.
  *
- * @return
- *   Ignored.
- *
  * @see signup_close_signup()
  */
 function hook_signup_close($node) {
@@ -149,10 +140,10 @@ function hook_signup_close($node) {
  * implementation of this hook returns TRUE, no signup information will be
  * printed for that node.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully-loaded node object being viewed.
  *
- * @return
+ * @return bool|null
  *   TRUE if you want to prevent signup information from being printed, FALSE
  *   or NULL if the information should be printed.
  *
@@ -177,9 +168,9 @@ function hook_signup_suppress($node) {
  * so if anyone returns TRUE, access is granted. If everyone returns FALSE,
  * access is denied (even if the Signup module would normally grant access).
  *
- * @param $node
+ * @param stdClass $node
  *   The fully-loaded node object where the menu items would be attached.
- * @param $menu_type
+ * @param string $menu_type
  *   String specifying what kind of menu item to test access for. Can be:
  *   'signup': the signup form
  *   'list': the signup attendee listing
@@ -188,7 +179,7 @@ function hook_signup_suppress($node) {
  *          that signups are currently open on the given node).
  *   'broadcast': for the broadcast tab
  *
- * @return
+ * @return bool
  *   TRUE if you want to allow access to the requested menu item, FALSE if you
  *   want to deny access (although if another hook implementation returns
  *   TRUE, that will take precedence), or NULL if you don't care and want to
diff --git a/signup.module b/signup.module
index 8d91cc4..96b0659 100644
--- a/signup.module
+++ b/signup.module
@@ -410,9 +410,9 @@ function signup_menu() {
  * This ensures that the node is signup enabled, and that that the current
  * user should have permission to view the requested menu item type.
  *
- * @param $node
+ * @param stdClass $node
  *   The fully loaded node object from the menu autoloader.
- * @param $menu_type
+ * @param string $menu_type
  *   String specifying what kind of menu item to test access for.  Can be:
  *   'signup': the signup form
  *   'list': the signup attendee listing
@@ -423,7 +423,7 @@ function signup_menu() {
  *   'broadcast': for the broadcast tab
  *   'any': if the user has permission to see any of these
  *
- * @return
+ * @return bool
  *   TRUE if the current node is signup enabled and the current user has
  *   permisison to access to requested menu item, otherwise FALSE.
  *
@@ -518,12 +518,12 @@ function signup_menu_load($sid) {
 /**
  * Determine menu access callback for a specific signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object that would be affected.
- * @param $op
+ * @param string $op
  *   The operation the menu item would perform. Can be 'edit' or 'cancel'.
  *
- * @return
+ * @return bool
  *   TRUE if the operation should be permitted, otherwise FALSE.
  */
 function _signup_menu_signup_access($signup, $op) {
@@ -563,12 +563,9 @@ function signup_current_user_signup_page($node) {
  * see if they can administer signups and redirect there. Finally, if they can
  * at least send a signup broadcast, go there.
  *
- * @param $node
+ * @param stdClass $node
  *   Fully loaded node object to generate the node/N/signup menu handler for.
  *
- * @return
- *   Either the output of the default task ("Sign up") or redirect to a tab.
- *
  * @see signup_menu()
  * @see _signup_menu_access()
  */
@@ -755,6 +752,8 @@ function signup_form_alter(&$form, &$form_state, $form_id) {
 }
 
 /**
+ * Implements hook_form_FORM_ID_alter().
+ *
  * Alters the form for administrator settings per node type.
  * (admin/content/types)
  */
@@ -928,9 +927,11 @@ function signup_node_view($node, $view_mode = 'full') {
  * Helper function that determines if a given node should have any
  * signup-related output.
  *
- * @param $node A fully loaded node object.
+ * @param stdClass $node
+ *   A fully loaded node object.
  *
- * @return TRUE if this node should have signup output, FALSE if not.
+ * @return bool
+ *   TRUE if this node should have signup output, FALSE if not.
  *
  * @see signup_nodeapi()
  */
@@ -973,7 +974,7 @@ function signup_action_info() {
 /**
  * Action callback to cancel a given signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Reference to a fully-loaded signup object to cancel.
  *
  * @see signup_load_signup()
@@ -987,10 +988,10 @@ function signup_cancel_action($signup) {
 /**
  * Action callback to mark a given signup that the user attended the node.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Reference to a fully-loaded signup object to record attendance on.
  *
- * @return
+ * @return none
  *   Nothing: $signup object is modified by reference and the {signup_log}
  *   table is directly UPDATE'ed in the database.
  */
@@ -1010,10 +1011,10 @@ function signup_mark_attended_action(&$signup) {
 /**
  * Action callback to mark a given signup that the user didn't attend the node.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Reference to a fully-loaded signup object to record attendance on.
  *
- * @return
+ * @return none
  *   Nothing: $signup object is modified by reference and the {signup_log}
  *   table is directly UPDATE'ed in the database.
  */
@@ -1053,10 +1054,10 @@ function signup_views_bulk_operations_object_info() {
  * method also adds a "label" member to the object which is used by Views bulk
  * operations (VBO) in various parts of its UI.
  *
- * @param $sid
+ * @param int $sid
  *   Signup ID to load.
  *
- * @return
+ * @return stdClass
  *   Fully loaded $signup object corresponding to the given ID.
  */
 function signup_load_signup($sid) {
@@ -1071,10 +1072,10 @@ function signup_load_signup($sid) {
 /**
  * Save a $signup object to the database.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Fully-loaded signup object to save.
  *
- * @return
+ * @return SAVED_NEW|SAVED_UPDATED|false
  *   The return value from drupal_write_record().
  *
  * @see signup_load_signup()
@@ -1113,10 +1114,10 @@ function signup_save_signup(&$signup) {
 /**
  * Retrieve a list of all users who have signed up for a node.
  *
- * @param $nid
+ * @param int $nid
  *   The node ID to retrieve signups for.
  *
- * @return
+ * @return array
  *   An array of $signup objects containing all columns from {signup_log}
  *   along with the 'name', 'mail', and 'language' columns from {users}.
  */
@@ -1156,11 +1157,11 @@ function signup_content_extra_fields($type_name) {
 /**
  * Cancel the given signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   Information about the signup to cancel. Can be either the integer signup
  *   ID (sid), or a full object of data about the signup (a complete row from
  *   the {signup_log} table.
- * @param $notify_user
+ * @param bool $notify_user
  *   When set to TRUE, a confirmation message is displayed via
  *   drupal_set_message().
  */
@@ -1216,7 +1217,13 @@ function signup_valid_token($token, $sid, $operation) {
 }
 
 /**
- * Callback function for closing signups
+ * Callback function for closing signups.
+ *
+ * @param int $nid
+ *   The node ID of the node to which signups are being opened.
+ * @param string $cron
+ *   A string indicating whether the callback is being executed by cron.
+ *
  * @ingroup signup_callback
  */
 function signup_close_signup($nid, $cron = 'no') {
@@ -1239,7 +1246,13 @@ function signup_close_signup($nid, $cron = 'no') {
 }
 
 /**
- * Callback function for reopening signups
+ * Callback function for reopening signups.
+ *
+ * @param int $nid
+ *   The node ID of the node to which signups are being opened.
+ * @param string $cron
+ *   A string indicating whether the callback is being executed by cron.
+ *
  * @ingroup signup_callback
  */
 function signup_open_signup($nid, $cron = 'no') {
@@ -1282,31 +1295,32 @@ function signup_content_types() {
  * NOTE: other modules can call this function. To do so, $signup_form
  * must be as follows:
  *
- * $signup_form['nid'] : nid of the node to which the user will be signed up
- * $signup_form['uid'] : uid of the user to sign up
- * $signup_form['signup_anon_mail'] : Optional. An email address of an
- *   anonymous user to sign up. Only include this if the user is not
- *   already registered with the site.  $signup_form['uid'] will
- *   automatically be set to 0 if this element is passed in. NOTE: It's
- *   highly recommended to call the signup_validate_anon_email
- *   function in the external module's validation cycle or perform
- *   that function's validation logic prior to passing in this element!
- * $signup_form['signup_form_data'] : an array of key/value pairs --
- *   key is the data category, value is the user input
- *
- * @param $notify_user
+ * @param array $signup_form
+ *   $signup_form['nid'] : nid of the node to which the user will be signed up
+ *   $signup_form['uid'] : uid of the user to sign up
+ *   $signup_form['signup_anon_mail'] : Optional. An email address of an
+ *     anonymous user to sign up. Only include this if the user is not
+ *     already registered with the site.  $signup_form['uid'] will
+ *     automatically be set to 0 if this element is passed in. NOTE: It's
+ *     highly recommended to call the signup_validate_anon_email
+ *     function in the external module's validation cycle or perform
+ *     that function's validation logic prior to passing in this element!
+ *   $signup_form['signup_form_data'] : an array of key/value pairs --
+ *     key is the data category, value is the user input
+ *
+ * @param bool $notify_user
  *   When set to TRUE, confirmation messages are displayed via
  *   drupal_set_message() and confirmation/forwarding emails are sent if
  *   enabled for the current node.
  *
- * @param $reset_node_load
+ * @param bool $reset_node_load
  *   When set to TRUE, node_load() is called with the optional reset
  *   argument as TRUE. This can sometimes be helpful when signups
  *   have been opened with signup_open_signup() since that function
  *   can cause static caching of the node object, thus leading to the
  *   $node->signup_status check here failing when it should not.
  *
- * @return
+ * @return int|false
  *   The signup id (SID) if the user was successfully signed up, FALSE if the
  *   user is already signed up or signups are not allowed on the given node.
  */
@@ -1432,12 +1446,12 @@ function signup_sign_up_user($signup_form, $notify_user = TRUE, $reset_node_load
  * If callers wish to honor this configuration, they must test
  * $node->signup_send_confirmation themselves.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object representing the user's signup.
- * @param $node
+ * @param stdClass $node
  *   The fully-loaded node object which the user signed up to.
  *
- * @return
+ * @return array|false
  *   The return value from drupal_mail() if the mail is sent, or FALSE if the
  *   confirmation was aborted for some reason (node not configured to send it,
  *   user doesn't have a valid e-mail address, etc).
@@ -1464,12 +1478,12 @@ function signup_send_confirmation_mail($signup, $node) {
 /**
  * Send the signup forwarding mail when a user signs up for something.
  *
- * @param $signup
+ * @param stdClass $signup
  *   The fully-loaded signup object representing the user's signup.
- * @param $node
+ * @param stdClass $node
  *   The fully-loaded node object which the user signed up to.
  *
- * @return
+ * @return array|false
  *   The return value from drupal_mail() if the mail is sent, or FALSE if the
  *   messsage is aborted for some reason (node not configured to send it,
  *   user doesn't have a valid e-mail address, etc).
@@ -1524,12 +1538,12 @@ function signup_send_forwarding_mail($signup, $node) {
  * signup status (open vs. closed) and prints a message indicating
  * what happened.
  *
- * @param $node
+ * @param stdClass $node
  *  The node to update, can be a full $node object or a numeric nid.
- * @param $type
+ * @param stdClass $type
  *  String indicating what changed -- can be either 'limit' or 'total'.
  *
- * @return
+ * @return int
  *  A flag indicating what change (if any) to the signup status was
  *  required due to the change in limit.  0 if there was no change, -1
  *  if signups are now closed, and 1 if signups are now open.
@@ -1618,11 +1632,11 @@ function signup_views_api() {
  *
  * Constructs all of the email messages generated by the signup module.
  *
- * @param $key
+ * @param string $key
  *   Unique key to indicate what message to build.
- * @param $message
+ * @param array $message
  *   Reference to the message array being built.
- * @param $params
+ * @param array $params
  *   Array of parameters to indicate what text to include in the message body.
  *   If $params['ignore_tokens'] is TRUE, none of the signup-provided tokens
  *   in the message body will be replaced, otherwise, tokens are replaced
@@ -1654,13 +1668,13 @@ function signup_mail($key, &$message, $params) {
  * These are the hard-coded tokens provided by signup.module which are
  * available even when token.module is not enabled.
  *
- * @param $node
+ * @param stdClass $node
  *   An object with info about the signup-enabled node. Must contain
  *   at least 'nid', 'title', and 'TODO: time?' fields.
- * @param $signup
+ * @param stdClass $signup
  *   An object with info about the user who signed up.
  *
- * @return
+ * @return array
  *   An array of tokens and their replacement values.
  */
 function _signup_get_email_tokens($node, $signup) {
@@ -1701,10 +1715,10 @@ function _signup_get_email_tokens($node, $signup) {
 /**
  * Get the email address to use for a given signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   An object containing signup data, in particular 'mail' and 'anon_mail'.
  *
- * @return
+ * @return string
  *   The appropriate email address to use to contact the signed up user.
  */
 function _signup_get_email($signup) {
@@ -1714,13 +1728,13 @@ function _signup_get_email($signup) {
 /**
  * Get the name to use for a given signup.
  *
- * @param $signup
+ * @param stdClass $signup
  *   A fully-loaded signup object.
- * @param $link
+ * @param bool $link
  *   Optional boolean indicating that the name should be rendered as a link to
  *   the user's profile (if it's an authenticated signup).
  *
- * @return
+ * @return string
  *   The appropriate name to use for the signed up user.
  */
 function _signup_get_username($signup, $link = FALSE) {
@@ -1749,6 +1763,9 @@ function _signup_get_username($signup, $link = FALSE) {
 
 /**
  * Generate a link to cancel a given signup.
+ *
+ * @param int $sid
+ *   The signup ID.
  */
 function _signup_get_cancel_link($sid) {
   $token = signup_get_token($sid, 'cancel');
@@ -1758,11 +1775,11 @@ function _signup_get_cancel_link($sid) {
 /**
  * Implements hook_panels_include_directory().
  *
- * @param $plugin_type
+ * @param string $plugin_type
  *   The plugin type for which the Panels engine is currently requesting the
  *   location of an include directory.
  *
- * @return
+ * @return string
  *   The location of the include directory for plugin type being requested,
  *   relative to the base directory of the module implementing this hook.
  */
diff --git a/theme/admin.inc b/theme/admin.inc
index 3e37e72..9121e49 100644
--- a/theme/admin.inc
+++ b/theme/admin.inc
@@ -13,14 +13,14 @@
  * results by signup status, which is rendered at the top of the page by
  * default.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables containing:
  *   - 'filter_status_form': HTML representation of the signup status filter
  *     form.
  *   - 'signup_admin_form': HTML representation of the main signup
  *     administration form.
  *
- * @return
+ * @return string
  *   Themed output for the signup administration overview page.
  */
 function theme_signup_admin_page($variables) {
diff --git a/theme/email.inc b/theme/email.inc
index b4bb511..94aa5e5 100644
--- a/theme/email.inc
+++ b/theme/email.inc
@@ -7,8 +7,11 @@
 /**
  * Return the value for the %user_signup_info email token for custom signup data.
  *
- * @param $signup_data
- *   Array of custom data for a particular signup.
+ * @param array $signup_data
+ *   Custom data for a particular signup.
+ *
+ * @return string
+ *   Plain text output.
  *
  * @see theme_signup_user_form()
  * @see theme_signup_custom_data_email()
@@ -24,10 +27,10 @@ function theme_signup_email_token_custom_data($variables) {
  * nested data), so if you override it, be sure not to change the part
  * where it does "call_user_func(__FUNCTION__)".
  *
- * @param $data
- *   Array of custom user signup data.
+ * @param array $data
+ *   An array of custom user signup data.
  *
- * @return
+ * @return string
  *   Plain text output with newlines.
  *
  * @see theme_signup_user_form()
@@ -53,12 +56,12 @@ function theme_signup_custom_data_email($variables) {
 /**
  * Renders a single custom signup form field into unfiltered output.
  *
- * @param $key
+ * @param string $key
  *   Name of the custom signup field (the array key).
- * @param $value
+ * @param string $value
  *   Value of the custom signup field (the array value).
  *
- * @return
+ * @return string
  *   Plain text output to display this key/value pair.
  *
  * @see theme_signup_user_form()
@@ -79,12 +82,12 @@ function theme_signup_custom_data_field_text($variables) {
 /**
  * Controls the body of the copy of the broadcast message sent to the sender.
  *
- * @param $raw_message
+ * @param string $raw_message
  *   The raw message typed in by the sender with no tokens replaced.
- * @param $cooked_message
+ * @param string $cooked_message
  *   The message after all the tokens have been replaced.
  *
- * @return
+ * @return string
  *   The final text to put in the email body sent to the broadcast sender.
  */
 function theme_signup_broadcast_sender_copy($variables) {
diff --git a/theme/node.admin.inc b/theme/node.admin.inc
index cf9abb8..ef5ea1c 100644
--- a/theme/node.admin.inc
+++ b/theme/node.admin.inc
@@ -13,7 +13,7 @@
  * signup_node_admin_page()), and if the node is signup-enabled, the
  * form to signup other users.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables including:
  *   - 'node': The node object for the signup-enabled node this is a tab on.
  *   - 'signup_node_admin_summary_form': The rendered HTML for the signup node
@@ -125,11 +125,11 @@ function theme_signup_node_admin_details_form($variables) {
  * nested data), so if you override it, be sure not to change the part
  * where it does "call_user_func(__FUNCTION__)".
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables including:
  *   - 'data': Array of custom user signup data.
  *
- * @return
+ * @return string
  *   User data directly formatted in divs.
  *
  * @see theme_signup_user_form()
diff --git a/theme/node.inc b/theme/node.inc
index 4a5dbf4..edaf460 100644
--- a/theme/node.inc
+++ b/theme/node.inc
@@ -7,13 +7,13 @@
 /**
  * Controls the output displayed if this node is closed for signups.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables containing:
  *   - 'node': The fully loaded node object.
  *   - 'current_signup': If the user already signed up, an HTML representation
  *     of their current signup information, otherwise an empty string.
  *
- * @return
+ * @return string
  *   Themed output to display for a node with closed signups.
  *
  * @see _signup_node_output()
@@ -31,13 +31,13 @@ function theme_signup_signups_closed($variables) {
 /**
  * Controls the output for anonymous users who can't signup.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables containing:
  *   - 'anon_login_text': The translated HTML help text telling users to login
  *     (and if allowed on this site, register) so they can signup, including
  *     login/register links.
  *
- * @return
+ * @return string
  *   The themed HTML to display the login (and maybe register) help text.
  */
 function theme_signup_anonymous_user_login_text($variables) {
@@ -49,11 +49,11 @@ function theme_signup_anonymous_user_login_text($variables) {
 /**
  * Return HTML desired at the top of the signup output for a node.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables containing:
  *   - 'node': The fully loaded node object to generate a header for.
  *
- * @return
+ * @return string
  *   HTML to display at the top of the signup output.
  *
  * @see _signup_node_output()
diff --git a/theme/signup_form.inc b/theme/signup_form.inc
index 5440feb..e7c8d99 100644
--- a/theme/signup_form.inc
+++ b/theme/signup_form.inc
@@ -33,11 +33,11 @@
  * If you do not want any additional fields, the function can simply
  * return an empty array: "return array();"
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables including:
  *   - 'node': The fully loaded node object where this signup form is appearing.
  *
- * @return
+ * @return array
  *   Array defining the form to present to the user to signup for a node.
  *
  * @see theme_signup_anonymous_username()
@@ -82,12 +82,12 @@ function theme_signup_user_form($variables) {
  * This value is used for the %user_name email token for anonymous users, and
  * also to identify a particular anonymous signup in various places in the UI.
  *
- * @param $variables
+ * @param array $variables
  *   An array of variables including:
  *   - 'form_data': Array of custom signup form values for the current signup.
  *   - 'email': E-mail address of the anonymous user who signed up.
  *
- * @return
+ * @return string
  *   A string with the proper value for the %user_name email token.
  *
  * @see theme_signup_user_form()
-- 
1.7.8.2