Skip to:
Content

BuddyPress.org


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

Improve inline docs in bp-core. See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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.