Changeset 10163 for trunk/src/bp-xprofile/bp-xprofile-template.php

Timestamp:

10/01/2015 04:18:13 AM (9 years ago)

Author:

tw2113

Message:

First pass of documentation cleanup for the XProfile Component.

See #6406.

File:

• trunk/src/bp-xprofile/bp-xprofile-template.php (modified) (43 diffs)

trunk/src/bp-xprofile/bp-xprofile-template.php

@@ -116 +116 @@
      * @since 2.4.0 Introduced `$member_type` argument.
      *
-     * @param array $args {
+     * @param array|string $args {
      *     An array of arguments. All items are optional.
      *
@@ -134 +134 @@
     public function __construct( $args = '' ) {
 
-        // Backward compatibility with old method of passing arguments
+        // Backward compatibility with old method of passing arguments.
         if ( ! is_array( $args ) || func_num_args() > 1 ) {
             _deprecated_argument( __METHOD__, '2.3.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) );
@@ -224 +224 @@
             do_action( 'xprofile_template_loop_end' );
 
-            // Do some cleaning up after the loop
+            // Do some cleaning up after the loop.
             $this->rewind_groups();
         }
@@ -238 +238 @@
         $group = $this->next_group();
 
-        // loop has just started
+        // Loop has just started.
         if ( 0 === $this->current_group ) {
 
@@ -285 +285 @@
             return true;
         } elseif ( $this->current_field + 1 == $this->field_count ) {
-            // Do some cleaning up after the loop
+            // Do some cleaning up after the loop.
             $this->rewind_fields();
         }
@@ -297 +297 @@
         $field = $this->next_field();
 
-        // Valid field values of 0 or '0' get caught by empty(), so we have an extra check for these. See #BP5731
+        // Valid field values of 0 or '0' get caught by empty(), so we have an extra check for these. See #BP5731.
         if ( ! empty( $field->data ) && ( ! empty( $field->data->value ) || ( '0' === $field->data->value ) ) ) {
             $value = maybe_unserialize( $field->data->value );
@@ -313 +313 @@
 
 /**
- * Query for XProfile groups and fields
+ * Query for XProfile groups and fields.
  *
  * @since 1.0.0
@@ -320 +320 @@
  * @see BP_XProfile_Group::get() for full description of `$args` array.
  *
- * @param array $args {
+ * @param array|string $args {
  *     Array of arguments. See BP_XProfile_Group::get() for full description. Those arguments whose defaults differ
  *     from that method are described here:
@@ -339 +339 @@
 
     // Only show empty fields if we're on the Dashboard, or we're on a user's
-    // profile edit page, or this is a registration page
+    // profile edit page, or this is a registration page.
     $hide_empty_fields_default = ( ! is_network_admin() && ! is_admin() && ! bp_is_user_profile_edit() && ! bp_is_register_page() );
 
-    // We only need to fetch visibility levels when viewing your own profile
+    // We only need to fetch visibility levels when viewing your own profile.
     if ( bp_is_my_profile() || bp_current_user_can( 'bp_moderate' ) || bp_is_register_page() ) {
         $fetch_visibility_level_default = true;
@@ -349 +349 @@
     }
 
-    // Parse arguments
+    // Parse arguments.
     $r = bp_parse_args( $args, array(
         'user_id'                => bp_displayed_user_id(),
@@ -359 +359 @@
         'fetch_field_data'       => true,
         'fetch_visibility_level' => $fetch_visibility_level_default,
-        'exclude_groups'         => false, // Comma-separated list of profile field group IDs to exclude
-        'exclude_fields'         => false, // Comma-separated list of profile field IDs to exclude
+        'exclude_groups'         => false, // Comma-separated list of profile field group IDs to exclude.
+        'exclude_fields'         => false, // Comma-separated list of profile field IDs to exclude.
         'update_meta_cache'      => true,
     ), 'has_profile' );
 
-    // Populate the template loop global
+    // Populate the template loop global.
     $profile_template = new BP_XProfile_Data_Template( $r );
 
@@ -405 +405 @@
         }
 
-        // Set a class with the field ID
+        // Set a class with the field ID.
         $css_classes[] = 'field_' . $profile_template->field->id;
 
-        // Set a class with the field name (sanitized)
+        // Set a class with the field name (sanitized).
         $css_classes[] = 'field_' . sanitize_title( $profile_template->field->name );
 
-        // Set a class indicating whether the field is required or optional
+        // Set a class indicating whether the field is required or optional.
         if ( ! empty( $profile_template->field->is_required ) ) {
             $css_classes[] = 'required-field';
@@ -418 +418 @@
         }
 
-        // Add the field visibility level
+        // Add the field visibility level.
         $css_classes[] = 'visibility-' . esc_attr( bp_get_the_profile_field_visibility_level() );
 
@@ -531 +531 @@
         global $group;
 
-        // Build the form action URL
+        // Build the form action URL.
         $form_action = trailingslashit( bp_displayed_user_domain() . bp_get_profile_slug() . '/edit/group/' . $group->id );
 
@@ -750 +750 @@
 
 /**
- * Returns the action name for any signup errors related to this profile field
+ * Returns the action name for any signup errors related to this profile field.
  *
  * In the registration templates, signup errors are pulled from the global
@@ -759 +759 @@
  *
  * @since 1.8.0
- * @return string The _errors action name corresponding to this profile field
+ *
+ * @return string The _errors action name corresponding to this profile field.
  */
 function bp_get_the_profile_field_errors_action() {
@@ -767 +768 @@
 
 /**
- * bp_the_profile_field_options()
- *
  * Displays field options HTML for field types of 'selectbox', 'multiselectbox',
  * 'radio', 'checkbox', and 'datebox'.
  *
- * @package BuddyPress Xprofile
  * @since 1.1.0
  *
@@ -783 +781 @@
 }
     /**
-     * bp_get_the_profile_field_options()
-     *
      * Retrieves field options HTML for field types of 'selectbox', 'multiselectbox', 'radio', 'checkbox', and 'datebox'.
      *
-     * @package BuddyPress Xprofile
      * @since 1.1.0
      *
@@ -795 +790 @@
      * @param array $args {
      *     Array of optional arguments.
-     *     @type string|bool $type Type of datebox. False if it's not a
-     *           datebox, otherwise 'day, 'month', or 'year'. Default: false.
-     *     @type int $user_id ID of the user whose profile values should be
-     *           used when rendering options. Default: displayed user.
+     *     @type string|bool $type    Type of datebox. False if it's not a
+     *                                datebox, otherwise 'day, 'month', or 'year'. Default: false.
+     *     @type int         $user_id ID of the user whose profile values should be
+     *                                used when rendering options. Default: displayed user.
      * }
+     *
+     * @return string $vaue Field options markup.
      */
     function bp_get_the_profile_field_options( $args = array() ) {
@@ -839 +836 @@
         global $field;
 
-        // Define locale variable(s)
+        // Define locale variable(s).
         $retval = false;
 
-        // Super admins can skip required check
+        // Super admins can skip required check.
         if ( bp_current_user_can( 'bp_moderate' ) && !is_admin() ) {
             $retval = false;
 
-        // All other users will use the field's setting
+        // All other users will use the field's setting.
         } elseif ( isset( $field->is_required ) ) {
             $retval = $field->is_required;
@@ -862 +859 @@
 
 /**
- * Echo the visibility level of this field
+ * Echo the visibility level of this field.
  */
 function bp_the_profile_field_visibility_level() {
@@ -868 +865 @@
 }
     /**
-     * Return the visibility level of this field
+     * Return the visibility level of this field.
      */
     function bp_get_the_profile_field_visibility_level() {
@@ -875 +872 @@
         // On the registration page, values stored in POST should take
         // precedence over default visibility, so that submitted values
-        // are not lost on failure
+        // are not lost on failure.
         if ( bp_is_register_page() && ! empty( $_POST['field_' . $field->id . '_visibility'] ) ) {
             $retval = esc_attr( $_POST['field_' . $field->id . '_visibility'] );
@@ -893 +890 @@
 
 /**
- * Echo the visibility level label of this field
+ * Echo the visibility level label of this field.
  */
 function bp_the_profile_field_visibility_level_label() {
@@ -899 +896 @@
 }
     /**
-     * Return the visibility level label of this field
+     * Return the visibility level label of this field.
      */
     function bp_get_the_profile_field_visibility_level_label() {
@@ -906 +903 @@
         // On the registration page, values stored in POST should take
         // precedence over default visibility, so that submitted values
-        // are not lost on failure
+        // are not lost on failure.
         if ( bp_is_register_page() && ! empty( $_POST['field_' . $field->id . '_visibility'] ) ) {
             $level = esc_html( $_POST['field_' . $field->id . '_visibility'] );
@@ -959 +956 @@
  * Get all profile field groups.
  *
- * @since  2.1.0
+ * @since 2.1.0
  *
  * @return object $groups
@@ -984 +981 @@
  * Check if there is more than one group of fields for the profile being edited.
  *
- * @since  2.1.0
+ * @since 2.1.0
  *
  * @return bool True if there is more than one profile field group.
@@ -1005 +1002 @@
  *
  * @since 1.0.0
- *
- * @return string Field group tabs markup.
  */
 function bp_profile_group_tabs() {
@@ -1021 +1016 @@
 
 /**
- * Return the XProfile group tabs
+ * Return the XProfile group tabs.
  *
  * @since 2.3.0
@@ -1029 +1024 @@
 function bp_get_profile_group_tabs() {
 
-    // Get field group data
+    // Get field group data.
     $groups     = bp_profile_get_field_groups();
     $group_name = bp_get_profile_group_name();
     $tabs       = array();
 
-    // Loop through field groups and put a tab-lst together
+    // Loop through field groups and put a tab-lst together.
     for ( $i = 0, $count = count( $groups ); $i < $count; ++$i ) {
 
-        // Setup the selected class
+        // Setup the selected class.
         $selected = '';
         if ( $group_name === $groups[ $i ]->name ) {
@@ -1043 +1038 @@
         }
 
-        // Skip if group has no fields
+        // Skip if group has no fields.
         if ( empty( $groups[ $i ]->fields ) ) {
             continue;
         }
 
-        // Build the profile field group link
+        // Build the profile field group link.
         $link   = trailingslashit( bp_displayed_user_domain() . bp_get_profile_slug() . '/edit/group/' . $groups[ $i ]->id );
 
-        // Add tab to end of tabs array
+        // Add tab to end of tabs array.
         $tabs[] = sprintf(
             '<li %1$s><a href="%2$s">%3$s</a></li>',
@@ -1083 +1078 @@
     function bp_get_profile_group_name() {
 
-        // Check action variable
+        // Check action variable.
         $group_id = bp_action_variable( 1 );
         if ( empty( $group_id ) || ! is_numeric( $group_id ) ) {
@@ -1089 +1084 @@
         }
 
-        // Check for cached group
+        // Check for cached group.
         $group = new BP_XProfile_Group( $group_id );
 
@@ -1143 +1138 @@
          * Filters the current profile group ID.
          *
-         * Possible values are admin/profile/edit/[group-id]
+         * Possible values are admin/profile/edit/[group-id].
          *
          * @since 1.1.0
@@ -1183 +1178 @@
 
 /**
- * Echo the field visibility radio buttons
+ * Echo the field visibility radio buttons.
+ *
+ * @param array|string $args Args for the radio buttons.
  */
 function bp_profile_visibility_radio_buttons( $args = '' ) {
@@ -1189 +1186 @@
 }
     /**
-     * Return the field visibility radio buttons
+     * Return the field visibility radio buttons.
+     *
+     * @param array|string $args Args for the radio buttons.
+     *
+     * @return string $retval
      */
     function bp_profile_get_visibility_radio_buttons( $args = '' ) {
 
-        // Parse optional arguments
+        // Parse optional arguments.
         $r = bp_parse_args( $args, array(
             'field_id'     => bp_get_the_profile_field_id(),
@@ -1203 +1204 @@
         ), 'xprofile_visibility_radio_buttons' );
 
-        // Empty return value, filled in below if a valid field ID is found
+        // Empty return value, filled in below if a valid field ID is found.
         $retval = '';
 
-        // Only do-the-do if there's a valid field ID
+        // Only do-the-do if there's a valid field ID.
         if ( ! empty( $r['field_id'] ) ) :
 
-            // Start the output buffer
+            // Start the output buffer.
             ob_start();
 
-            // Output anything before
+            // Output anything before.
             echo $r['before']; ?>
 
@@ -1232 +1233 @@
             <?php endif;
 
-            // Output anything after
+            // Output anything after.
             echo $r['after'];
 
-            // Get the output buffer and empty it
+            // Get the output buffer and empty it.
             $retval = ob_get_clean();
         endif;
@@ -1252 +1253 @@
 
 /**
- * Output the XProfile field visibility select list for settings
+ * Output the XProfile field visibility select list for settings.
  *
  * @since 2.0.0
+ *
+ * @param array|string $args Args for the select list.
  */
 function bp_profile_settings_visibility_select( $args = '' ) {
@@ -1260 +1263 @@
 }
     /**
-     * Return the XProfile field visibility select list for settings
+     * Return the XProfile field visibility select list for settings.
      *
      * @since 2.0.0
+     *
+     * @param array|string $args Args for the select list.
+     *
+     * @return string $retval
      */
     function bp_profile_get_settings_visibility_select( $args = '' ) {
 
-        // Parse optional arguments
+        // Parse optional arguments.
         $r = bp_parse_args( $args, array(
             'field_id' => bp_get_the_profile_field_id(),
@@ -1274 +1281 @@
         ), 'xprofile_settings_visibility_select' );
 
-        // Empty return value, filled in below if a valid field ID is found
+        // Empty return value, filled in below if a valid field ID is found.
         $retval = '';
 
-        // Only do-the-do if there's a valid field ID
+        // Only do-the-do if there's a valid field ID.
         if ( ! empty( $r['field_id'] ) ) :
 
-            // Start the output buffer
+            // Start the output buffer.
             ob_start();
 
-            // Output anything before
+            // Output anything before.
             echo $r['before']; ?>
 
@@ -1305 +1312 @@
             <?php endif;
 
-            // Output anything after
+            // Output anything after.
             echo $r['after'];
 
-            // Get the output buffer and empty it
+            // Get the output buffer and empty it.
             $retval = ob_get_clean();
         endif;