WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/17/2008 12:40:10 AM (17 years ago)
Author:
ryan
Message:

phpdoc for wp-admin/includes from jacobsantos. see #7527

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-admin/includes/image.php

    r8879 r8912  
    44 *
    55 * @package WordPress
    6  */
    7 
    8 /**
    9  * wp_create_thumbnail() - Create a thumbnail from an Image given a maximum side size.
    10  *
    11  * @package WordPress
    12  * @param   mixed   $file   Filename of the original image, Or attachment id
    13  * @param   int     $max_side   Maximum length of a single side for the thumbnail
    14  * @return  string          Thumbnail path on success, Error string on failure
    15  *
    16  * This function can handle most image file formats which PHP supports.
    17  * If PHP does not have the functionality to save in a file of the same format, the thumbnail will be created as a jpeg.
     6 * @subpackage Administration
     7 */
     8
     9/**
     10 * Create a thumbnail from an Image given a maximum side size.
     11 *
     12 * This function can handle most image file formats which PHP supports. If PHP
     13 * does not have the functionality to save in a file of the same format, the
     14 * thumbnail will be created as a jpeg.
     15 *
     16 * @since unknown
     17 *
     18 * @param mixed $file Filename of the original image, Or attachment id.
     19 * @param int $max_side Maximum length of a single side for the thumbnail.
     20 * @return string Thumbnail path on success, Error string on failure.
    1821 */
    1922function wp_create_thumbnail( $file, $max_side, $deprecated = '' ) {
    20 
    2123    $thumbpath = image_resize( $file, $max_side, $max_side );
    2224    return apply_filters( 'wp_create_thumbnail', $thumbpath );
    … …  
    2426
    2527/**
    26  * wp_crop_image() - Crop an Image to a given size.
    27  *
    28  * @package WordPress
     28 * Crop an Image to a given size.
     29 *
    2930 * @internal Missing Long Description
    30  * @param   int $src_file   The source file
    31  * @param   int $src_x      The start x position to crop from
    32  * @param   int $src_y      The start y position to crop from
    33  * @param   int $src_w      The width to crop
    34  * @param   int $src_h      The height to crop
    35  * @param   int $dst_w      The destination width
    36  * @param   int $dst_h      The destination height
    37  * @param   int $src_abs    If the source crop points are absolute
    38  * @param   int $dst_file   The destination file to write to
    39  * @return  string          New filepath on success, String error message on failure
    40  *
     31 *
     32 * @since unknown
     33 *
     34 * @param string|int $src_file The source file or Attachment ID
     35 * @param int $src_x The start x position to crop from.
     36 * @param int $src_y The start y position to crop from.
     37 * @param int $src_w The width to crop.
     38 * @param int $src_h The height to crop.
     39 * @param int $dst_w The destination width.
     40 * @param int $dst_h The destination height.
     41 * @param int $src_abs Optional. If the source crop points are absolute.
     42 * @param string $dst_file Optional. The destination file to write to.
     43 * @return string New filepath on success, String error message on failure.
    4144 */
    4245function wp_crop_image( $src_file, $src_x, $src_y, $src_w, $src_h, $dst_w, $dst_h, $src_abs = false, $dst_file = false ) {
    … …  
    7578
    7679/**
    77  * wp_generate_attachment_metadata() - Generate post Image attachment Metadata
    78  *
    79  * @package WordPress
     80 * Generate post Image attachment Metadata.
     81 *
    8082 * @internal Missing Long Description
    81  * @param   int     $attachment_id  Attachment Id to process
    82  * @param   string  $file   Filepath of the Attached image
    83  * @return  mixed           Metadata for attachment
    84  *
     83 *
     84 * @since unknown
     85 *
     86 * @param int $attachment_id Attachment Id to process
     87 * @param string $file Filepath of the Attached image
     88 * @return mixed Metadata for attachment
    8589 */
    8690function wp_generate_attachment_metadata( $attachment_id, $file ) {
    … …  
    121125
    122126    }
     127
    123128    return apply_filters( 'wp_generate_attachment_metadata', $metadata );
    124129}
    125130
    126131/**
    127  * wp_load_image() - Load an image which PHP Supports.
    128  *
    129  * @package WordPress
     132 * Load an image which PHP Supports.
     133 *
    130134 * @internal Missing Long Description
    131  * @param   string  $file   Filename of the image to load
    132  * @return  resource        The resulting image resource on success, Error string on failure.
    133  *
     135 *
     136 * @since unknown
     137 *
     138 * @param string $file Filename of the image to load.
     139 * @return resource The resulting image resource on success, Error string on failure.
    134140 */
    135141function wp_load_image( $file ) {
    … …  
    154160
    155161/**
    156  * get_udims() - Calculated the new dimentions for downsampled images
    157  *
    158  * @package WordPress
    159  * @internal Missing Description
     162 * Calculated the new dimentions for downsampled images.
     163 *
     164 * @since unknown
    160165 * @see wp_shrink_dimensions()
    161  * @param   int     $width  Current width of the image
    162  * @param   int     $height Current height of the image
    163  * @return  mixed           Array(height,width) of shrunk dimensions.
     166 *
     167 * @param int $width Current width of the image
     168 * @param int $height Current height of the image
     169 * @return mixed Array(height,width) of shrunk dimensions.
    164170 *
    165171 */
    … …  
    167173    return wp_shrink_dimensions( $width, $height );
    168174}
    169 /**
    170  * wp_shrink_dimensions() - Calculates the new dimentions for a downsampled image.
    171  *
    172  * @package WordPress
    173  * @internal Missing Long Description
    174  * @param   int     $width  Current width of the image
    175  * @param   int     $height Current height of the image
    176  * @param   int     $wmax   Maximum wanted width
    177  * @param   int     $hmax   Maximum wanted height
    178  * @return  mixed           Array(height,width) of shrunk dimensions.
     175
     176/**
     177 * Calculates the new dimentions for a downsampled image.
     178 *
     179 * @since unknown
     180 * @see wp_constrain_dimensions()
     181 *
     182 * @param int $width Current width of the image
     183 * @param int $height Current height of the image
     184 * @param int $wmax Maximum wanted width
     185 * @param int $hmax Maximum wanted height
     186 * @return mixed Array(height,width) of shrunk dimensions.
    179187 *
    180188 */
    … …  
    183191}
    184192
    185 // convert a fraction string to a decimal
     193/**
     194 * Convert a fraction string to a decimal.
     195 *
     196 * @since unknown
     197 *
     198 * @param string $str
     199 * @return int|float
     200 */
    186201function wp_exif_frac2dec($str) {
    187202    @list( $n, $d ) = explode( '/', $str );
    … …  
    191206}
    192207
    193 // convert the exif date format to a unix timestamp
     208/**
     209 * Convert the exif date format to a unix timestamp.
     210 *
     211 * @since unknown
     212 *
     213 * @param string $str
     214 * @return int
     215 */
    194216function wp_exif_date2ts($str) {
    195     // seriously, who formats a date like 'YYYY:MM:DD hh:mm:ss'?
    196217    @list( $date, $time ) = explode( ' ', trim($str) );
    197218    @list( $y, $m, $d ) = explode( ':', $date );
    … …  
    200221}
    201222
    202 // get extended image metadata, exif or iptc as available
     223/**
     224 * Get extended image metadata, exif or iptc as available
     225 *
     226 * @since unknown
     227 *
     228 * @param string $file
     229 * @return bool|array False on failure. Image metadata array on success.
     230 */
    203231function wp_read_image_metadata( $file ) {
    204232    if ( !file_exists( $file ) )
    … …  
    207235    list(,,$sourceImageType) = getimagesize( $file );
    208236
    209     // exif contains a bunch of data we'll probably never need formatted in ways that are difficult to use.
    210     // We'll normalize it and just extract the fields that are likely to be useful.  Fractions and numbers
    211     // are converted to floats, dates to unix timestamps, and everything else to strings.
     237    // exif contains a bunch of data we'll probably never need formatted in ways
     238    // that are difficult to use. We'll normalize it and just extract the fields
     239    // that are likely to be useful.  Fractions and numbers are converted to
     240    // floats, dates to unix timestamps, and everything else to strings.
    212241    $meta = array(
    213242        'aperture' => 0,
    … …  
    223252    );
    224253
    225     // read iptc first, since it might contain data not available in exif such as caption, description etc
     254    // read iptc first, since it might contain data not available in exif such
     255    // as caption, description etc
    226256    if ( is_callable('iptcparse') ) {
    227257        getimagesize($file, $info);
    … …  
    232262            elseif ( !empty($iptc['2#080'][0]) ) // byline
    233263                $meta['credit'] = utf8_encode(trim($iptc['2#080'][0]));
    234             if ( !empty($iptc['2#055'][0]) and !empty($iptc['2#060'][0]) ) // created datee and time
     264            if ( !empty($iptc['2#055'][0]) and !empty($iptc['2#060'][0]) ) // created date and time
    235265                $meta['created_timestamp'] = strtotime($iptc['2#055'][0] . ' ' . $iptc['2#060'][0]);
    236266            if ( !empty($iptc['2#120'][0]) ) // caption
    … …  
    259289            $meta['shutter_speed'] = wp_exif_frac2dec( $exif['ExposureTime'] );
    260290    }
    261     // FIXME: try other exif libraries if available
     291    /** @todo FIXME: try other exif libraries if available */
    262292
    263293    return apply_filters( 'wp_read_image_metadata', $meta, $file, $sourceImageType );
    … …  
    265295}
    266296
    267 // is the file a real image file?
     297/**
     298 * Validate that file is an image.
     299 *
     300 * @since unknown
     301 *
     302 * @param string $path File path to test if valid image.
     303 * @return bool True if valid image, false if not valid image.
     304 */
    268305function file_is_valid_image($path) {
    269306    $size = @getimagesize($path);
    … …  
    271308}
    272309
    273 // is the file an image suitable for displaying within a web page?
     310/**
     311 * Validate that file is suitable for displaying within a web page.
     312 *
     313 * @since unknown
     314 * @uses apply_filters() Calls 'file_is_displayable_image' on $result and $path.
     315 *
     316 * @param string $path File path to test.
     317 * @return bool True if suitable, false if not suitable.
     318 */
    274319function file_is_displayable_image($path) {
    275320    $info = @getimagesize($path);
Note: See TracChangeset for help on using the changeset viewer.