Update docblocks and formatting.

Author: DFurnes

lib/modules/dosomething/dosomething_northstar/dosomething_northstar.module

@@ -108,8 +108,8 @@ function dosomething_northstar_register_user($form_state) {
 }
 
 /**
- * Build the drupal_http_request object for nothstar calls.
- * This will be depricated once guzzle is fixed...
+ * Build the drupal_http_request object for Northstar calls.
+ * @returns array
  */
 function _dosomething_northstar_build_http_client() {
   $base_url = NORTHSTAR_URL;
@@ -131,7 +131,10 @@ function _dosomething_northstar_build_http_client() {
 }
 
 /**
- * Send user profile updates to northstar.
+ * Update a user's existing Northstar profile based on
+ * their Drupal ID.
+ * 
+ * @return void
  */
 function dosomething_northstar_update_user($form_state) {
   $user = $form_state['user'];
@@ -159,6 +162,7 @@ function dosomething_northstar_update_user($form_state) {
 
 /**
  * If the log is enabled, log this request to the database.
+ * Get user profile data from Northstar for the given Drupal ID.
  *
  * @param string $op - label for the operation being performed
  * @param object $user - the Drupal user
@@ -188,9 +192,7 @@ function dosomething_northstar_log_request($op, $user, $request_body, $response)
 }
 
 /**
- * Get user data from northstar.
- *
- * @param  int  $id Drupal user id.
+ * @param int $drupal_id Drupal user id.
  * @return object
  */
 function dosomething_northstar_get_northstar_user($id) {
@@ -221,11 +223,10 @@ function dosomething_northstar_get_northstar_user($id) {
 }
 
 /**
- * Build a user json object, that's accepted by Northstar.
- *
- * @param obj $user
- *  Drupal user object
+ * Build a user JSON object in the format that Northstar expects.
  *
+ * @param $user - Drupal user object
+ * @return array
  */
 function dosomething_northstar_build_ns_user($user, $form_state) {
   // Optional fields

lib/modules/dosomething/dosomething_user/dosomething_user.module

@@ -268,6 +268,8 @@ function dosomething_user_form_alter(&$form, $form_state, $form_id) {
         _dosomething_user_add_signup_data($form);
       }
       else {
+        // If this is not the registration form, then register submit handler
+        // to update that existing Northstar user by their Drupal ID.
         $form['#submit'][] = 'dosomething_user_update_user';
       }
 
@@ -424,13 +426,13 @@ function dosomething_user_validate_address_field($form, &$form_state) {
   }
 }
 
-/** 
+/**
  * Validates address for dosomething_user_info_form
  *
  * @param array $form
- * A drupal form. 
+ * A drupal form.
  * @param array $form_state
- * A drupal form_state array. 
+ * A drupal form_state array.
  */
 function dosomething_user_validate_info_form_address ($form, &$form_state) {
   $first_name = $form_state['input']['first_name'];
@@ -439,7 +441,7 @@ function dosomething_user_validate_info_form_address ($form, &$form_state) {
    'country' => 'US',
    'thoroughfare' => $form_state['input']['street'],
    'premise' => $form_state['input']['sub_street'],
-   'locality' => $form_state['input']['city'], 
+   'locality' => $form_state['input']['city'],
    'administrative_area' => $form_state['input']['state'],
    'postal_code' => $form_state['input']['zipcode'],
   ];
@@ -466,7 +468,7 @@ function dosomething_user_validate_info_form_address ($form, &$form_state) {
 }
 
 /**
- * Validates that password is 6 or more characters long.  
+ * Validates that password is 6 or more characters long.
  *
  * @param array $form
  *  A drupal form.
@@ -588,9 +590,15 @@ function dosomething_user_user_login(&$form_state, $account) {
 
 /**
  *
+ * Custom form submission handler to update an existing user.
+ * Triggered when making changes on the user profile form.
+ * 
+ * @param $form
+ * @param $form_state
  */
 function dosomething_user_update_user($form, &$form_state) {
   if (!module_exists('dosomething_northstar')) { return; }
+  
   // Forward user updates into Northstar.
   dosomething_northstar_update_user($form_state);
 }
@@ -775,7 +783,8 @@ function dosomething_user_is_old_person($user = NULL) {
 }
 
 /**
- * Custom login submission handler.
+ * Custom login submission handler. This does _not_ trigger on log-ins
+ * that happen post-registration.
  */
 function dosomething_user_login_submit($form, &$form_state) {
   // Trigger an analytics event on login
@@ -815,7 +824,7 @@ function dosomething_user_authentication_submit($form, &$form_state) {
     dosomething_northstar_register_user($form_state);
   }
 
-  // After all logins, except reportback pages redirect to page user was just on.
+  // After all log-ins, except reportback pages redirect to page user was just on.
   if (isset($source) && stripos($source, 'reportback') > 0) {
     $form_state['redirect'] = drupal_get_path_alias($_SERVER['HTTP_REFERER']);
   }
@@ -1402,7 +1411,7 @@ function dosomething_user_info_form($form, &$form_state, $account) {
     '#type' => 'textfield',
     '#default_value' => $birthday,
     '#description' => t("Format: M/D/YYYY"),
-    '#field_suffix' => 'User age: ' . $age, 
+    '#field_suffix' => 'User age: ' . $age,
   );
   $form['picture'] = array(
     '#type' => 'fieldset',