Skip to:
Content

BuddyPress.org

Changeset 7433


Ignore:
Timestamp:
10/16/2013 01:36:51 PM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

Location:
trunk/bp-core
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-core/bp-core-actions.php

    r7380 r7433  
    22
    33/**
    4  * BuddyPress Filters & Actions
     4 * BuddyPress Filters & Actions.
    55 *
    66 * @package BuddyPress
    … …  
    1717
    1818/**
    19  * Attach BuddyPress to WordPress
     19 * Attach BuddyPress to WordPress.
    2020 *
    2121 * BuddyPress uses its own internal actions to help aid in third-party plugin

  • trunk/bp-core/bp-core-admin.php

    r7427 r7433  
    22
    33/**
    4  * Main BuddyPress Admin Class
     4 * Main BuddyPress Admin Class.
    55 *
    66 * @package BuddyPress
    … …  
    1313if ( !class_exists( 'BP_Admin' ) ) :
    1414/**
    15  * Loads BuddyPress plugin admin area
     15 * Load BuddyPress plugin admin area.
    1616 *
    1717 * @package BuddyPress
    1818 * @subpackage CoreAdministration
    19  * @since BuddyPress (1.6)
     19 *
     20 * @since BuddyPress (1.6.0)
    2021 */
    2122class BP_Admin {
    … …  
    2425
    2526    /**
    26      * @var string Path to the BuddyPress admin directory
     27     * Path to the BuddyPress admin directory.
     28     *
     29     * @var string $admin_dir
    2730     */
    2831    public $admin_dir = '';
    … …  
    3134
    3235    /**
    33      * @var string URL to the BuddyPress admin directory
     36     * URL to the BuddyPress admin directory.
     37     *
     38     * @var string $admin_url
    3439     */
    3540    public $admin_url = '';
    3641
    3742    /**
    38      * @var string URL to the BuddyPress images directory
     43     * URL to the BuddyPress images directory.
     44     *
     45     * @var string $images_url
    3946     */
    4047    public $images_url = '';
    4148
    4249    /**
    43      * @var string URL to the BuddyPress admin CSS directory
     50     * URL to the BuddyPress admin CSS directory.
     51     *
     52     * @var string $css_url
    4453     */
    4554    public $css_url = '';
    4655
    4756    /**
    48      * @var string URL to the BuddyPress admin JS directory
     57     * URL to the BuddyPress admin JS directory.
     58     *
     59     * @var string
    4960     */
    5061    public $js_url = '';
    … …  
    5364
    5465    /**
    55      * The main BuddyPress admin loader
    56      *
    57      * @since BuddyPress (1.6)
    58      *
    59      * @uses BP_Admin::setup_globals() Setup the globals needed
    60      * @uses BP_Admin::includes() Include the required files
    61      * @uses BP_Admin::setup_actions() Setup the hooks and actions
     66     * The main BuddyPress admin loader.
     67     *
     68     * @since BuddyPress (1.6.0)
     69     *
     70     * @uses BP_Admin::setup_globals() Setup the globals needed.
     71     * @uses BP_Admin::includes() Include the required files.
     72     * @uses BP_Admin::setup_actions() Setup the hooks and actions.
    6273     */
    6374    public function __construct() {
    … …  
    6879
    6980    /**
    70      * Admin globals
    71      *
    72      * @since BuddyPress (1.6)
     81     * Set admin-related globals.
     82     *
    7383     * @access private
     84     * @since BuddyPress (1.6.0)
    7485     */
    7586    private function setup_globals() {
    … …  
    8899
    89100    /**
    90      * Include required files
    91      *
    92      * @since BuddyPress (1.6)
     101     * Include required files.
     102     *
     103     * @since BuddyPress (1.6.0)
    93104     * @access private
    94105     */
    … …  
    102113
    103114    /**
    104      * Setup the admin hooks, actions and filters
    105      *
    106      * @since BuddyPress (1.6)
     115     * Set up the admin hooks, actions, and filters.
     116     *
    107117     * @access private
    108      *
    109      * @uses add_action() To add various actions
    110      * @uses add_filter() To add various filters
     118     * @since BuddyPress (1.6.0)
     119     *
     120     * @uses add_action() To add various actions.
     121     * @uses add_filter() To add various filters.
    111122     */
    112123    private function setup_actions() {
    … …  
    139150
    140151    /**
    141      * Add the navigational menu elements
     152     * Add the navigational menu elements.
    142153     *
    143154     * @since BuddyPress (1.6)
    144155     *
    145      * @uses add_management_page() To add the Recount page in Tools section
     156     * @uses add_management_page() To add the Recount page in Tools section.
    146157     * @uses add_options_page() To add the Forums settings page in Settings
    147      *                           section
     158     *       section.
    148159     */
    149160    public function admin_menus() {
    … …  
    227238
    228239    /**
    229      * Register the settings
    230      *
    231      * @since BuddyPress (1.6)
    232      *
    233      * @uses add_settings_section() To add our own settings section
    234      * @uses add_settings_field() To add various settings fields
    235      * @uses register_setting() To register various settings
     240     * Register the settings.
     241     *
     242     * @since BuddyPress (1.6.0)
     243     *
     244     * @uses add_settings_section() To add our own settings section.
     245     * @uses add_settings_field() To add various settings fields.
     246     * @uses register_setting() To register various settings.
    236247     */
    237248    public function register_admin_settings() {
    … …  
    316327
    317328    /**
    318      * Add Settings link to plugins area
    319      *
    320      * @since BuddyPress (1.6)
    321      *
    322      * @param array $links Links array in which we would prepend our link
    323      * @param string $file Current plugin basename
    324      * @return array Processed links
     329     * Add Settings link to plugins area.
     330     *
     331     * @since BuddyPress (1.6.0)
     332     *
     333     * @param array $links Links array in which we would prepend our link.
     334     * @param string $file Current plugin basename.
     335     * @return array Processed links.
    325336     */
    326337    public function modify_plugin_action_links( $links, $file ) {
    … …  
    338349
    339350    /**
    340      * Add some general styling to the admin area
    341      *
    342      * @since BuddyPress (1.6)
     351     * Add some general styling to the admin area.
     352     *
     353     * @since BuddyPress (1.6.0)
    343354     */
    344355    public function admin_head() {
    … …  
    354365
    355366    /**
    356      * Add some general styling to the admin area
    357      *
    358      * @since BuddyPress (1.6)
     367     * Add some general styling to the admin area.
     368     *
     369     * @since BuddyPress (1.6.0)
    359370     */
    360371    public function enqueue_scripts() {
    … …  
    370381
    371382    /**
    372      * Output the about screen
    373      *
    374      * @since BuddyPress (1.7)
     383     * Output the about screen.
     384     *
     385     * @since BuddyPress (1.7.0)
    375386     */
    376387    public function about_screen() {
    … …  
    481492
    482493    /**
    483      * Output the credits screen
    484      *
    485      * Hardcoding this in here is pretty janky. It's fine for 2.2, but we'll
     494     * Output the credits screen.
     495     *
     496     * Hardcoding this in here is pretty janky. It's fine for now, but we'll
    486497     * want to leverage api.wordpress.org eventually.
    487498     *
    488      * @since BuddyPress (1.7)
     499     * @since BuddyPress (1.7.0)
    489500     */
    490501    public function credits_screen() {
    … …  
    613624
    614625/**
    615  * Setup BuddyPress Admin
     626 * Setup BuddyPress Admin.
    616627 *
    617  * @since BuddyPress (1.6)
     628 * @since BuddyPress (1.6.0)
    618629 *
    619630 * @uses BP_Admin

  • trunk/bp-core/bp-core-adminbar.php

    r7228 r7433  
    22
    33/**
    4  * BuddyPress Core Toolbar
     4 * BuddyPress Core Toolbar.
    55 *
    6  * Handles the core functions related to the WordPress Toolbar
     6 * Handles the core functions related to the WordPress Toolbar.
    77 *
    88 * @package BuddyPress
    … …  
    1414
    1515/**
    16  * Adds the secondary BuddyPress area to the my-account menu
     16 * Add the secondary BuddyPress area to the my-account menu.
    1717 *
    18  * @since BuddyPress 1.6
     18 * @since BuddyPress (1.6.0)
     19 *
    1920 * @global WP_Admin_Bar $wp_admin_bar
    2021 */
    … …  
    4445
    4546/**
    46  * Handle the Toolbar/BuddyBar business
     47 * Handle the Toolbar/BuddyBar business.
    4748 *
    48  * @since BuddyPress (1.2)
     49 * @since BuddyPress (1.2.0)
    4950 *
    5051 * @global string $wp_version
    … …  
    5354 * @uses bp_use_wp_admin_bar()
    5455 * @uses show_admin_bar()
    55  * @uses add_action() To hook 'bp_adminbar_logo' to 'bp_adminbar_logo'
    56  * @uses add_action() To hook 'bp_adminbar_login_menu' to 'bp_adminbar_menus'
    57  * @uses add_action() To hook 'bp_adminbar_account_menu' to 'bp_adminbar_menus'
    58  * @uses add_action() To hook 'bp_adminbar_thisblog_menu' to 'bp_adminbar_menus'
    59  * @uses add_action() To hook 'bp_adminbar_random_menu' to 'bp_adminbar_menus'
    60  * @uses add_action() To hook 'bp_core_admin_bar' to 'wp_footer'
    61  * @uses add_action() To hook 'bp_core_admin_bar' to 'admin_footer'
     56 * @uses add_action() To hook 'bp_adminbar_logo' to 'bp_adminbar_logo'.
     57 * @uses add_action() To hook 'bp_adminbar_login_menu' to 'bp_adminbar_menus'.
     58 * @uses add_action() To hook 'bp_adminbar_account_menu' to 'bp_adminbar_menus'.
     59 * @uses add_action() To hook 'bp_adminbar_thisblog_menu' to 'bp_adminbar_menus'.
     60 * @uses add_action() To hook 'bp_adminbar_random_menu' to 'bp_adminbar_menus'.
     61 * @uses add_action() To hook 'bp_core_admin_bar' to 'wp_footer'.
     62 * @uses add_action() To hook 'bp_core_admin_bar' to 'admin_footer'.
    6263 */
    6364function bp_core_load_admin_bar() {
    … …  
    8990
    9091/**
    91  * Handle the Toolbar CSS
     92 * Handle the Toolbar CSS.
    9293 *
    93  * @since BuddyPress 1.5
     94 * @since BuddyPress (1.5.0)
    9495 */
    9596function bp_core_load_admin_bar_css() {

  • trunk/bp-core/bp-core-avatars.php

    r7428 r7433  
    22
    33/**
    4  * BuddyPress Avatars
     4 * BuddyPress Avatars.
    55 */
    66
    … …  
    99
    1010/***
    11  * Set up the constants we need for avatar support
     11 * Set up the constants we need for avatar support.
    1212 */
    1313function bp_core_set_avatar_constants() {
    … …  
    5151add_action( 'bp_init', 'bp_core_set_avatar_constants', 3 );
    5252
     53/**
     54 * Set up global variables related to avatars.
     55 *
     56 * @since BuddyPress (1.5.0)
     57 */
    5358function bp_core_set_avatar_globals() {
    5459    $bp = buddypress();
    … …  
    478483
    479484/**
    480  * Delete an existing avatar
    481  *
    482  * Accepted values for $args are:
    483  *  item_id - item id which relates to the object type.
    484  *  object - the objetc type user, group, blog, etc.
    485  *  avatar_dir - The directory where the avatars to be uploaded.
    486  *
    487  * @param mixed $args
    488  * @return bool Success/failure
     485 * Delete an existing avatar.
     486 *
     487 * @param array $args {
     488 *     Array of function parameters.
     489 *     @type bool|int $item_id ID of the item whose avatar you're deleting.
     490 *           Defaults to the current item of type $object.
     491 *     @type string $object Object type of the item whose avatar you're
     492 *           deleting. 'user', 'group', 'blog', or custom. Default: 'user'.
     493 *     @type bool|string $avatar_dir Subdirectory where avatar is located.
     494 *           Default: false, which falls back on the default location
     495 *           corresponding to the $object.
     496 * }
     497 * @return bool True on success, false on failure.
    489498 */
    490499function bp_core_delete_existing_avatar( $args = '' ) {
    … …  
    546555
    547556/**
    548  * Handles avatar uploading.
    549  *
    550  * The functions starts off by checking that the file has been uploaded properly using bp_core_check_avatar_upload().
    551  * It then checks that the file size is within limits, and that it has an accepted file extension (jpg, gif, png).
    552  * If everything checks out, crop the image and move it to its real location.
    553  *
    554  * @param array $file The appropriate entry the from $_FILES superglobal.
    555  * @param string $upload_dir_filter A filter to be applied to upload_dir
    556  * @return bool Success/failure
     557 * Handle avatar uploading.
     558 *
     559 * The functions starts off by checking that the file has been uploaded
     560 * properly using bp_core_check_avatar_upload(). It then checks that the file
     561 * size is within limits, and that it has an accepted file extension (jpg, gif,
     562 * png). If everything checks out, crop the image and move it to its real
     563 * location.
     564 *
    557565 * @see bp_core_check_avatar_upload()
    558566 * @see bp_core_check_avatar_type()
     567 *
     568 * @param array $file The appropriate entry the from $_FILES superglobal.
     569 * @param string $upload_dir_filter A filter to be applied to 'upload_dir'.
     570 * @return bool True on success, false on failure.
    559571 */
    560572function bp_core_avatar_handle_upload( $file, $upload_dir_filter ) {
    … …  
    672684
    673685/**
    674  * Crop an uploaded avatar
     686 * Crop an uploaded avatar.
    675687 *
    676688 * $args has the following parameters:
    … …  
    684696 *  crop_y - The vertical starting point of the crop
    685697 *
    686  * @param mixed $args
    687  * @return bool Success/failure
     698 * @param array $args {
     699 *     Array of function parameters.
     700 *     @type string $object Object type of the item whose avatar you're
     701 *           handling. 'user', 'group', 'blog', or custom. Default: 'user'.
     702 *     @type string $avatar_dir Subdirectory where avatar should be stored.
     703 *           Default: 'avatars'.
     704 *     @type bool|int $item_id ID of the item that the avatar belongs to.
     705 *     @type bool|string $original_file Absolute papth to the original avatar
     706 *           file.
     707 *     @type int $crop_w Crop width. Default: the global 'full' avatar width,
     708 *           as retrieved by bp_core_avatar_full_width().
     709 *     @type int $crop_h Crop height. Default: the global 'full' avatar height,
     710 *           as retrieved by bp_core_avatar_full_height().
     711 *     @type int $crop_x The horizontal starting point of the crop. Default: 0.
     712 *     @type int $crop_y The vertical starting point of the crop. Default: 0.
     713 * }
     714 * @return bool True on success, false on failure.
    688715 */
    689716function bp_core_avatar_handle_crop( $args = '' ) {
    … …  
    764791
    765792/**
    766  * bp_core_fetch_avatar_filter()
    767  *
    768  * Attempts to filter get_avatar function and let BuddyPress have a go
    769  * at finding an avatar that may have been uploaded locally.
    770  *
    771  * @global array $authordata
    772  * @param string $avatar The result of get_avatar from before-filter
    773  * @param int|string|object $user A user ID, email address, or comment object
    774  * @param int $size Size of the avatar image (thumb/full)
    775  * @param string $default URL to a default image to use if no avatar is available
    776  * @param string $alt Alternate text to use in image tag. Defaults to blank
    777  * @return string
     793 * Replace default WordPress avatars with BP avatars, if available.
     794 *
     795 * Filters 'get_avatar'.
     796 *
     797 * @param string $avatar The avatar path passed to 'get_avatar'.
     798 * @param int|string|object $user A user ID, email address, or comment object.
     799 * @param int $size Size of the avatar image ('thumb' or 'full').
     800 * @param string $default URL to a default image to use if no avatar is available.
     801 * @param string $alt Alternate text to use in image tag. Default: ''.
     802 * @return string BP avatar path, if found; else the original avatar path.
    778803 */
    779804function bp_core_fetch_avatar_filter( $avatar, $user, $size, $default, $alt = '' ) {
    … …  
    816841
    817842/**
    818  * Has the current avatar upload generated an error?
    819  *
    820  * @param array $file
    821  * @return bool
     843 * Is the current avatar upload error-free?
     844 *
     845 * @param array $file The $_FILES array.
     846 * @return bool True if no errors are found. False if there are errors.
    822847 */
    823848function bp_core_check_avatar_upload( $file ) {
    … …  
    831856 * Is the file size of the current avatar upload permitted?
    832857 *
    833  * @param array $file
    834  * @return bool
     858 * @param array $file The $_FILES array.
     859 * @return bool True if the avatar is under the size limit, otherwise false.
    835860 */
    836861function bp_core_check_avatar_size( $file ) {
    … …  
    846871 * Permitted file types are JPG, GIF and PNG.
    847872 *
    848  * @param string $file
    849  * @return bool
     873 * @param array $file The $_FILES array.
     874 * @return bool True if the file extension is permitted, otherwise false.
    850875 */
    851876function bp_core_check_avatar_type($file) {
    … …  
    857882
    858883/**
    859  * Fetches data from the BP root blog's upload directory.
     884 * Fetch data from the BP root blog's upload directory.
    860885 *
    861886 * Handy for multisite instances because all uploads are made on the BP root
    … …  
    865890 * once to get what we need.
    866891 *
    867  * @since BuddyPress (1.8)
     892 * @since BuddyPress (1.8.0)
    868893 *
    869894 * @uses wp_upload_dir()
    870895 *
    871  * @param string $type The variable we want to return from the $bp->avatars object.
    872  *  Only 'upload_path' and 'url' are supported.
    873  * @return string
     896 * @param string $type The variable we want to return from the $bp->avatars
     897 *        object. Only 'upload_path' and 'url' are supported. Default: 'upload_path'.
     898 * @return string The avatar upload directory path.
    874899 */
    875900function bp_core_get_upload_dir( $type = 'upload_path' ) {
    … …  
    949974
    950975/**
    951  * bp_core_avatar_upload_path()
    952  *
    953  * Returns the absolute upload path for the WP installation
     976 * Get the absolute upload path for the WP installation.
    954977 *
    955978 * @uses wp_upload_dir To get upload directory info
    956  * @return string Absolute path to WP upload directory
     979 *
     980 * @return string Absolute path to WP upload directory.
    957981 */
    958982function bp_core_avatar_upload_path() {
    … …  
    961985
    962986/**
    963  * bp_core_avatar_url()
    964  *
    965  * Returns the raw base URL for root site upload location
    966  *
    967  * @uses wp_upload_dir To get upload directory info
    968  * @return string Full URL to current upload location
     987 * Get the raw base URL for root site upload location.
     988 *
     989 * @uses wp_upload_dir To get upload directory info.
     990 *
     991 * @return string Full URL to current upload location.
    969992 */
    970993function bp_core_avatar_url() {
    … …  
    973996
    974997/**
    975  * Check if a given user ID has an uploaded avatar
    976  *
    977  * @since BuddyPress (1.0)
    978  * @param int $user_id
    979  * @return boolean
     998 * Check if a given user ID has an uploaded avatar.
     999 *
     1000 * @since BuddyPress (1.0.0)
     1001 *
     1002 * @param int $user_id ID of the user whose avatar is being checked.
     1003 * @return bool True if the user has uploaded a local avatar. Otherwise false.
    9801004 */
    9811005function bp_get_user_has_avatar( $user_id = 0 ) {
    … …  
    9921016
    9931017/**
    994  * Utility function for fetching an avatar dimension setting
    995  *
    996  * @package BuddyPress
    997  * @since BuddyPress (1.5)
    998  *
    999  * @param string $type 'thumb' for thumbs, otherwise full
    1000  * @param string $h_or_w 'height' for height, otherwise width
    1001  * @return int $dim The dimension
     1018 * Utility function for fetching an avatar dimension setting.
     1019 *
     1020 * @since BuddyPress (1.5.0)
     1021 *
     1022 * @param string $type Dimension type you're fetching dimensions for. 'thumb'
     1023 *        or 'full'. Default: 'thumb'.
     1024 * @param string $h_or_w Which dimension is being fetched. 'height' or 'width'.
     1025 *        Default: 'height'.
     1026 * @return int $dim The dimension.
    10021027 */
    10031028function bp_core_avatar_dimension( $type = 'thumb', $h_or_w = 'height' ) {
    … …  
    10091034
    10101035/**
    1011  * Get the avatar thumb width setting
    1012  *
    1013  * @package BuddyPress
    1014  * @since BuddyPress (1.5)
    1015  *
    1016  * @return int The thumb width
     1036 * Get the 'thumb' avatar width setting.
     1037 *
     1038 * @since BuddyPress (1.5.0)
     1039 *
     1040 * @return int The 'thumb' width.
    10171041 */
    10181042function bp_core_avatar_thumb_width() {
    … …  
    10211045
    10221046/**
    1023  * Get the avatar thumb height setting
    1024  *
    1025  * @package BuddyPress
    1026  * @since BuddyPress (1.5)
    1027  *
    1028  * @return int The thumb height
     1047 * Get the 'thumb' avatar height setting.
     1048 *
     1049 * @since BuddyPress (1.5.0)
     1050 *
     1051 * @return int The 'thumb' height.
    10291052 */
    10301053function bp_core_avatar_thumb_height() {
    … …  
    10331056
    10341057/**
    1035  * Get the avatar full width setting
    1036  *
    1037  * @package BuddyPress
    1038  * @since BuddyPress (1.5)
    1039  *
    1040  * @return int The full width
     1058 * Get the 'full' avatar width setting
     1059 *
     1060 * @since BuddyPress (1.5.0)
     1061 *
     1062 * @return int The 'full' width.
    10411063 */
    10421064function bp_core_avatar_full_width() {
    … …  
    10451067
    10461068/**
    1047  * Get the avatar full height setting
    1048  *
    1049  * @package BuddyPress
    1050  * @since BuddyPress (1.5)
    1051  *
    1052  * @return int The full height
     1069 * Get the 'full' avatar height setting.
     1070 *
     1071 * @since BuddyPress (1.5.0)
     1072 *
     1073 * @return int The 'full' height.
    10531074 */
    10541075function bp_core_avatar_full_height() {
    … …  
    10571078
    10581079/**
    1059  * Get the max width for original avatar uploads
    1060  *
    1061  * @package BuddyPress
    1062  * @since BuddyPress (1.5)
    1063  *
    1064  * @return int The width
     1080 * Get the max width for original avatar uploads.
     1081 *
     1082 * @since BuddyPress (1.5.0)
     1083 *
     1084 * @return int The max width for original avatar uploads.
    10651085 */
    10661086function bp_core_avatar_original_max_width() {
    … …  
    10691089
    10701090/**
    1071  * Get the max filesize for original avatar uploads
    1072  *
    1073  * @package BuddyPress
    1074  * @since BuddyPress (1.5)
    1075  *
    1076  * @return int The filesize
     1091 * Get the max filesize for original avatar uploads.
     1092 *
     1093 * @since BuddyPress (1.5.0)
     1094 *
     1095 * @return int The max filesize for original avatar uploads.
    10771096 */
    10781097function bp_core_avatar_original_max_filesize() {
    … …  
    10811100
    10821101/**
    1083  * Get the default avatar
    1084  *
    1085  * @package BuddyPress
    1086  * @since BuddyPress (1.5)
    1087  *
    1088  * @return int The URL of the default avatar
     1102 * Get the URL of the 'full' default avatar.
     1103 *
     1104 * @since BuddyPress (1.5.0)
     1105 *
     1106 * @return string The URL of the default avatar.
    10891107 */
    10901108function bp_core_avatar_default() {
    … …  
    10931111
    10941112/**
    1095  * Get the default avatar thumb
    1096  *
    1097  * @package BuddyPress
    1098  * @since BuddyPress (1.5)
    1099  *
    1100  * @return int The URL of the default avatar thumb
     1113 * Get the URL of the 'thumb' default avatar.
     1114 *
     1115 * @since BuddyPress (1.5.0)
     1116 *
     1117 * @return string The URL of the default avatar thumb.
    11011118 */
    11021119function bp_core_avatar_default_thumb() {
Note: See TracChangeset for help on using the changeset viewer.