WordPress.org
Get WordPress

Make WordPress Core

Changeset 8912


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

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

Location:
trunk/wp-admin/includes
Files:
9 edited

Legend:

Unmodified
Added
Removed

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

    r8882 r8912  
    11<?php
     2/**
     3 * WordPress Comment Administration API
     4 *
     5 * @package WordPress
     6 * @subpackage Administration
     7 */
    28
    39/**
    … …  
    1925
    2026/**
    21  *
    22  *
     27 * {@internal Missing Short Description}}
     28 *
     29 * @since unknown
    2330 */
    2431function edit_comment() {
    … …  
    4249        }
    4350    }
    44 
    4551
    4652    if (!empty ( $_POST['edit_date'] ) ) {
    … …  
    6167}
    6268
     69/**
     70 * {@internal Missing Short Description}}
     71 *
     72 * @since unknown
     73 *
     74 * @param unknown_type $id
     75 * @return unknown
     76 */
    6377function get_comment_to_edit( $id ) {
    6478    if ( !$comment = get_comment($id) )
    … …  
    7993}
    8094
     95/**
     96 * {@internal Missing Short Description}}
     97 *
     98 * @since unknown
     99 * @uses $wpdb
     100 *
     101 * @param int $post_id Post ID
     102 * @return unknown
     103 */
    81104function get_pending_comments_num( $post_id ) {
    82105    global $wpdb;
    … …  
    105128}
    106129
    107 // Add avatars to relevant places in admin, or try to
    108 
     130/**
     131 * Add avatars to relevant places in admin, or try to.
     132 *
     133 * @since unknown
     134 * @uses $comment
     135 *
     136 * @param string $name User name.
     137 * @return string Avatar with Admin name.
     138 */
    109139function floated_admin_avatar( $name ) {
    110140    global $comment;

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

    r8845 r8912  
    11<?php
    2 
    3 // Registers dashboard widgets, handles POST data, sets up filters
     2/**
     3 * WordPress Dashboard Widget Administration Panel API
     4 *
     5 * @package WordPress
     6 * @subpackage Administration
     7 */
     8
     9/**
     10 * Registers dashboard widgets.
     11 *
     12 * handles POST data, sets up filters.
     13 *
     14 * @since unknown
     15 */
    416function wp_dashboard_setup() {
    517    global $wpdb, $wp_dashboard_sidebars;
    … …  
    194206}
    195207
    196 // Echoes out the dashboard
     208/**
     209 * Displays the dashboard.
     210 *
     211 * @since unknown
     212 */
    197213function wp_dashboard() {
    198214    echo "<div id='dashboard-widgets'>\n\n";
    … …  
    206222}
    207223
    208 // Makes sidebar_widgets option reflect the dashboard settings
     224/**
     225 * Makes sidebar_widgets option reflect the dashboard settings.
     226 *
     227 * @since unknown
     228 *
     229 * @return array WordPress Dashboard Widgets list.
     230 */
    209231function wp_dashboard_sidebars_widgets() { // hackery
    210232    return $GLOBALS['wp_dashboard_sidebars'];
    … …  
    213235// Modifies sidbar params on the fly to set up ids, class names, titles for each widget (called once per widget)
    214236// Switches widget to edit mode if $_GET['edit']
     237/**
     238 * {@internal Missing Short Description}}
     239 *
     240 * @since unknown
     241 *
     242 * @param unknown_type $params
     243 * @return unknown
     244 */
    215245function wp_dashboard_dynamic_sidebar_params( $params ) {
    216246    global $wp_registered_widgets, $wp_registered_widget_controls;
    … …  
    484514}
    485515
     516/**
     517 * Display recent comments dashboard widget content.
     518 *
     519 * @since unknown
     520 *
     521 * @param unknown_type $sidebar_args
     522 */
    486523function wp_dashboard_recent_comments( $sidebar_args ) {
    487524    global $comment;
    … …  
    537574}
    538575
    539 // $sidebar_args are handled by wp_dashboard_empty()
     576/**
     577 * Display incoming links dashboard widget content.
     578 *
     579 * $sidebar_args are handled by wp_dashboard_empty().
     580 *
     581 * @since unknown
     582 */
    540583function wp_dashboard_incoming_links_output() {
    541584    $widgets = get_option( 'dashboard_widget_options' );
    … …  
    597640}
    598641
    599 // $sidebar_args are handled by wp_dashboard_empty()
     642/**
     643 * {@internal Missing Short Description}}
     644 *
     645 * $sidebar_args are handled by wp_dashboard_empty().
     646 *
     647 * @since unknown
     648 *
     649 * @param int $widget_id
     650 */
    600651function wp_dashboard_rss_output( $widget_id ) {
    601652    $widgets = get_option( 'dashboard_widget_options' );
    … …  
    603654}
    604655
    605 // $sidebar_args are handled by wp_dashboard_empty()
     656/**
     657 * Display secondary dashboard RSS widget feed.
     658 *
     659 * $sidebar_args are handled by wp_dashboard_empty().
     660 *
     661 * @since unknown
     662 *
     663 * @return unknown
     664 */
    606665function wp_dashboard_secondary_output() {
    607666    $widgets = get_option( 'dashboard_widget_options' );
    … …  
    625684}
    626685
    627 // $sidebar_args are handled by wp_dashboard_empty()
     686/**
     687 * Display plugins most popular, newest plugins, and recently updated widget text.
     688 *
     689 * $sidebar_args are handled by wp_dashboard_empty().
     690 *
     691 * @since unknown
     692 */
    628693function wp_dashboard_plugins_output() {
    629694    $popular = @fetch_rss( 'http://wordpress.org/extend/plugins/rss/browse/popular/' );
    … …  
    673738}
    674739
    675 // Checks to see if all of the feed url in $check_urls are cached.
    676 // If $check_urls is empty, look for the rss feed url found in the dashboard widget optios of $widget_id.
    677 // If cached, call $callback, a function that echoes out output for this widget.
    678 // If not cache, echo a "Loading..." stub which is later replaced by AJAX call (see top of /wp-admin/index.php)
     740/**
     741 * Checks to see if all of the feed url in $check_urls are cached.
     742 *
     743 * If $check_urls is empty, look for the rss feed url found in the dashboard
     744 * widget optios of $widget_id. If cached, call $callback, a function that
     745 * echoes out output for this widget. If not cache, echo a "Loading..." stub
     746 * which is later replaced by AJAX call (see top of /wp-admin/index.php)
     747 *
     748 * @since unknown
     749 *
     750 * @param int $widget_id
     751 * @param callback $callback
     752 * @param array $check_urls RSS feeds
     753 * @return bool False on failure. True on success.
     754 */
    679755function wp_dashboard_cached_rss_widget( $widget_id, $callback, $check_urls = array() ) {
    680756    $loading = '<p class="widget-loading">' . __( 'Loading&#8230;' ) . '</p>';
    … …  
    712788}
    713789
    714 // Empty widget used for JS/AJAX created output.
    715 // Callback inserts content between before_widget and after_widget.  Used when widget is in edit mode.  Can also be used for custom widgets.
     790/**
     791 * Empty widget used for JS/AJAX created output.
     792 *
     793 * Callback inserts content between before_widget and after_widget. Used when
     794 * widget is in edit mode. Can also be used for custom widgets.
     795 *
     796 * @since unknown
     797 *
     798 * @param array $sidebar_args
     799 * @param callback $callback Optional. Only used in edit mode.
     800 */
    716801function wp_dashboard_empty( $sidebar_args, $callback = false ) {
    717802    extract( $sidebar_args, EXTR_SKIP );
    … …  
    733818}
    734819
    735 /* Dashboard Widgets Controls. Ssee also wp_dashboard_empty() */
     820/* Dashboard Widgets Controls. See also wp_dashboard_empty() */
    736821
    737822// Temp
    … …  
    741826
    742827// Calls widget_control callback
     828/**
     829 * Calls widget control callback.
     830 *
     831 * @since unknown
     832 *
     833 * @param int $widget_control_id Registered Widget ID.
     834 */
    743835function wp_dashboard_trigger_widget_control( $widget_control_id = false ) {
    744836    global $wp_registered_widget_controls;
    … …  
    747839}
    748840
    749 // Sets up $args to be used as input to wp_widget_rss_form(), handles POST data from RSS-type widgets
     841/**
     842 * The RSS dashboard widget control.
     843 *
     844 * Sets up $args to be used as input to wp_widget_rss_form(). Handles POST data
     845 * from RSS-type widgets.
     846 *
     847 * @since unknown
     848 *
     849 * @param array $args Expects 'widget_id' and 'form_inputs'.
     850 * @return bool|null False if no widget_id is given. Null on success.
     851 */
    750852function wp_dashboard_rss_control( $args ) {
    751853    extract( $args );

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

    r7965 r8912  
    11<?php
    2 
    3 // version number for the export format.  bump this when something changes that might affect compatibility.
     2/**
     3 * WordPress Export Administration API
     4 *
     5 * @package WordPress
     6 * @subpackage Administration
     7 */
     8
     9/**
     10 * Version number for the export format.
     11 *
     12 * Bump this when something changes that might affect compatibility.
     13 *
     14 * @since unknown
     15 * @var string
     16 */
    417define('WXR_VERSION', '1.0');
    518
     19/**
     20 * {@internal Missing Short Description}}
     21 *
     22 * @since unknown
     23 *
     24 * @param unknown_type $author
     25 */
    626function export_wp($author='') {
    727global $wpdb, $post_ids, $post;
    … …  
    2747$tags = (array) get_tags('get=all');
    2848
     49/**
     50 * {@internal Missing Short Description}}
     51 *
     52 * @since unknown
     53 *
     54 * @param unknown_type $categories
     55 */
    2956function wxr_missing_parents($categories) {
    3057    if ( !is_array($categories) || empty($categories) )
    … …  
    6289unset($categories);
    6390
     91/**
     92 * Place string in CDATA tag.
     93 *
     94 * @since unknown
     95 *
     96 * @param string $str String to place in XML CDATA tag.
     97 */
    6498function wxr_cdata($str) {
    6599    if ( seems_utf8($str) == false )
    … …  
    73107}
    74108
     109/**
     110 * {@internal Missing Short Description}}
     111 *
     112 * @since unknown
     113 *
     114 * @return string Site URL.
     115 */
    75116function wxr_site_url() {
    76117    global $current_site;
    … …  
    86127}
    87128
     129/**
     130 * {@internal Missing Short Description}}
     131 *
     132 * @since unknown
     133 *
     134 * @param object $c Category Object
     135 */
    88136function wxr_cat_name($c) {
    89137    if ( empty($c->name) )
    … …  
    93141}
    94142
     143/**
     144 * {@internal Missing Short Description}}
     145 *
     146 * @since unknown
     147 *
     148 * @param object $c Category Object
     149 */
    95150function wxr_category_description($c) {
    96151    if ( empty($c->description) )
    … …  
    100155}
    101156
     157/**
     158 * {@internal Missing Short Description}}
     159 *
     160 * @since unknown
     161 *
     162 * @param object $t Tag Object
     163 */
    102164function wxr_tag_name($t) {
    103165    if ( empty($t->name) )
    … …  
    107169}
    108170
     171/**
     172 * {@internal Missing Short Description}}
     173 *
     174 * @since unknown
     175 *
     176 * @param object $t Tag Object
     177 */
    109178function wxr_tag_description($t) {
    110179    if ( empty($t->description) )
    … …  
    114183}
    115184
     185/**
     186 * {@internal Missing Short Description}}
     187 *
     188 * @since unknown
     189 */
    116190function wxr_post_taxonomy() {
    117191    $categories = get_the_category();

  • 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);

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

    r8853 r8912  
    692692            'helps'      => __('Enter a link URL or click above for presets.'),
    693693        ),
    694         'menu_order'   => array(
     694        'menu_order'   => array(
    695695            'label'      => __('Order'),
    696696            'value'      => $edit_post->menu_order
    … …  
    14921492// support a GET parameter for disabling the flash uploader
    14931493function media_upload_use_flash($flash) {
    1494         if ( array_key_exists('flash', $_REQUEST) )
    1495                 $flash = !empty($_REQUEST['flash']);
    1496         return $flash;
     1494    if ( array_key_exists('flash', $_REQUEST) )
     1495        $flash = !empty($_REQUEST['flash']);
     1496    return $flash;
    14971497}
    14981498
    … …  
    15001500
    15011501function media_upload_flash_bypass() {
    1502         echo '<p class="upload-flash-bypass">';
    1503         printf( __('You are using the Flash uploader.  Problems?  Try the <a href="%s">Browser uploader</a> instead.'), clean_url(add_query_arg('flash', 0)) );
    1504         echo '</p>';
     1502    echo '<p class="upload-flash-bypass">';
     1503    printf( __('You are using the Flash uploader.  Problems?  Try the <a href="%s">Browser uploader</a> instead.'), clean_url(add_query_arg('flash', 0)) );
     1504    echo '</p>';
    15051505}
    15061506
    … …  
    15081508
    15091509function media_upload_html_bypass() {
    1510         echo '<p class="upload-html-bypass">';
    1511         if ( array_key_exists('flash', $_REQUEST) )
    1512                 // the user manually selected the browser uploader, so let them switch back to Flash
    1513                 printf( __('You are using the Browser uploader.  Try the <a href="%s">Flash uploader</a> instead.'), clean_url(add_query_arg('flash', 1)) );
    1514         else
    1515                 // the user probably doesn't have Flash
    1516                 printf( __('You are using the Browser uploader.') );
    1517 
    1518         echo '</p>';
     1510    echo '<p class="upload-html-bypass">';
     1511    if ( array_key_exists('flash', $_REQUEST) )
     1512        // the user manually selected the browser uploader, so let them switch back to Flash
     1513        printf( __('You are using the Browser uploader.  Try the <a href="%s">Flash uploader</a> instead.'), clean_url(add_query_arg('flash', 1)) );
     1514    else
     1515        // the user probably doesn't have Flash
     1516        printf( __('You are using the Browser uploader.') );
     1517
     1518    echo '</p>';
    15191519}
    15201520
    … …  
    15241524// make sure the GET parameter sticks when we submit a form
    15251525function media_upload_bypass_url($url) {
    1526         if ( array_key_exists('flash', $_REQUEST) )
    1527                 $url = add_query_arg('flash', intval($_REQUEST['flash']));
    1528         return $url;
     1526    if ( array_key_exists('flash', $_REQUEST) )
     1527        $url = add_query_arg('flash', intval($_REQUEST['flash']));
     1528    return $url;
    15291529}
    15301530

  • trunk/wp-admin/includes/plugin-install.php

    r8884 r8912  
    11<?php
    2 
    3 function plugins_api($action, $args = NULL) {
     2/**
     3 * WordPress Plugin Install Administration API
     4 *
     5 * @package WordPress
     6 * @subpackage Administration
     7 */
     8
     9/**
     10 * Retrieve plugin installer pages from WordPress Plugins API.
     11 *
     12 * It is possible for a plugin to override the Plugin API result with three
     13 * filters. Assume this is for plugins, which can extend on the Plugin Info to
     14 * offer more choices. This is very powerful and must be used with care, when
     15 * overridding the filters.
     16 *
     17 * The first filter, 'plugins_api_args', is for the args and gives the action as
     18 * the second parameter. The hook for 'plugins_api_args' must ensure that an
     19 * object is returned.
     20 *
     21 * The second filter, 'plugins_api', is the result that would be returned.
     22 *
     23 * @param string $action
     24 * @param array|object $args Optional. Arguments to serialize for the Plugin Info API.
     25 * @return mixed
     26 */
     27function plugins_api($action, $args = null) {
    428    global $wp_version;
    529
    … …  
    2044}
    2145
     46/**
     47 *
     48 *
     49 * @param unknown_type $args
     50 * @return unknown
     51 */
    2252function install_popular_tags( $args = array() ) {
    2353    if ( ! ($cache = wp_cache_get('popular_tags', 'api')) && ! ($cache = get_option('wporg_popular_tags')) )
    24         add_option('wporg_popular_tags', array(), '', 'no');///No autoload.
     54        add_option('wporg_popular_tags', array(), '', 'no'); ///No autoload.
    2555
    2656    if ( $cache && $cache->timeout + 3 * 60 * 60 > time() )

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

    r8735 r8912  
    9797}
    9898
     99/**
     100 * Check the plugins directory and retrieve all plugin files with plugin data.
     101 *
     102 * WordPress only supports plugin files in the base plugins directory
     103 * (wp-content/plugins) and in one directory above the plugins directory
     104 * (wp-content/plugins/my-plugin). The file it looks for has the plugin data and
     105 * must be found in those two locations. It is recommended that do keep your
     106 * plugin files in directories.
     107 *
     108 * The file with the plugin data is the file that will be included and therefore
     109 * needs to have the main execution for the plugin. This does not mean
     110 * everything must be contained in the file and it is recommended that the file
     111 * be split for maintainability. Keep everything in one file for extreme
     112 * optimization purposes.
     113 *
     114 * @since unknown
     115 *
     116 * @param string $plugin_folder Optional. Relative path to single plugin folder.
     117 * @return array Key is the plugin file path and the value is an array of the plugin data.
     118 */
    99119function get_plugins($plugin_folder = '') {
    100120
    … …  
    170190}
    171191
     192/**
     193 * Attempts activation of plugin in a "sandbox" and redirects on success.
     194 *
     195 * A plugin that is already activated will not attempt to be activated again.
     196 *
     197 * The way it works is by setting the redirection to the error before trying to
     198 * include the plugin file. If the plugin fails, then the redirection will not
     199 * be overwritten with the success message. Also, the options will not be
     200 * updated and the activation hook will not be called on plugin error.
     201 *
     202 * It should be noted that in no way the below code will actually prevent errors
     203 * within the file. The code should not be used elsewhere to replicate the
     204 * "sandbox", which uses redirection to work.
     205 * {@source 13 1}
     206 *
     207 * If any errors are found or text is outputted, then it will be captured to
     208 * ensure that the success redirection will update the error redirection.
     209 *
     210 * @since unknown
     211 *
     212 * @param string $plugin Plugin path to main plugin file with plugin data.
     213 * @param string $redirect Optional. URL to redirect to.
     214 * @return WP_Error|null WP_Error on invalid file or null on success.
     215 */
    172216function activate_plugin($plugin, $redirect = '') {
    173         $current = get_option('active_plugins');
    174         $plugin = trim($plugin);
    175 
    176         $valid = validate_plugin($plugin);
    177         if ( is_wp_error($valid) )
    178             return $valid;
    179 
    180         if ( !in_array($plugin, $current) ) {
    181             if ( !empty($redirect) )
    182                 wp_redirect(add_query_arg('_error_nonce', wp_create_nonce('plugin-activation-error_' . $plugin), $redirect)); // we'll override this later if the plugin can be included without fatal error
    183             ob_start();
    184             @include(WP_PLUGIN_DIR . '/' . $plugin);
    185             $current[] = $plugin;
    186             sort($current);
    187             update_option('active_plugins', $current);
    188             do_action('activate_' . $plugin);
    189             ob_end_clean();
    190         }
    191 
    192         return null;
    193 }
    194 
     217    $current = get_option('active_plugins');
     218    $plugin = trim($plugin);
     219
     220    $valid = validate_plugin($plugin);
     221    if ( is_wp_error($valid) )
     222        return $valid;
     223
     224    if ( !in_array($plugin, $current) ) {
     225        if ( !empty($redirect) )
     226            wp_redirect(add_query_arg('_error_nonce', wp_create_nonce('plugin-activation-error_' . $plugin), $redirect)); // we'll override this later if the plugin can be included without fatal error
     227        ob_start();
     228        @include(WP_PLUGIN_DIR . '/' . $plugin);
     229        $current[] = $plugin;
     230        sort($current);
     231        update_option('active_plugins', $current);
     232        do_action('activate_' . $plugin);
     233        ob_end_clean();
     234    }
     235
     236    return null;
     237}
     238
     239/**
     240 * Deactivate a single plugin or multiple plugins.
     241 *
     242 * The deactivation hook is disabled by the plugin upgrader by using the $silent
     243 * parameter.
     244 *
     245 * @since unknown
     246 *
     247 * @param string|array $plugins Single plugin or list of plugins to deactivate.
     248 * @param bool $silent Optional, default is false. Prevent calling deactivate hook.
     249 */
    195250function deactivate_plugins($plugins, $silent= false) {
    196251    $current = get_option('active_plugins');
    … …  
    210265}
    211266
     267/**
     268 * Activate multiple plugins.
     269 *
     270 * When WP_Error is returned, it does not mean that one of the plugins had
     271 * errors. It means that one or more of the plugins file path was invalid.
     272 *
     273 * The execution will be halted as soon as one of the plugins has an error.
     274 *
     275 * @since unknown
     276 *
     277 * @param string|array $plugins
     278 * @param string $redirect Redirect to page after successful activation.
     279 * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation.
     280 */
    212281function activate_plugins($plugins, $redirect = '') {
    213282    if ( !is_array($plugins) )
    … …  
    229298}
    230299
     300/**
     301 * Remove directory and files of a plugin for a single or list of plugin(s).
     302 *
     303 * If the plugins parameter list is empty, false will be returned. True when
     304 * completed.
     305 *
     306 * @since unknown
     307 *
     308 * @param array $plugins List of plugin
     309 * @param string $redirect Redirect to page when complete.
     310 * @return mixed
     311 */
    231312function delete_plugins($plugins, $redirect = '' ) {
    232313    global $wp_filesystem;
    … …  
    332413}
    333414
     415/**
     416 * Validate the plugin path.
     417 *
     418 * Checks that the file exists and {@link validate_file() is valid file}.
     419 *
     420 * @since unknown
     421 *
     422 * @param string $plugin Plugin Path
     423 * @return WP_Error|int 0 on success, WP_Error on failure.
     424 */
    334425function validate_plugin($plugin) {
    335426    if ( validate_file($plugin) )
    … …  
    344435 * Whether the plugin can be uninstalled.
    345436 *
    346  * @since 2.7
     437 * @since 2.7.0
    347438 *
    348439 * @param string $plugin Plugin path to check.
    … …  
    364455 * Calls the uninstall hook, if it is available.
    365456 *
    366  * @since 2.7
     457 * @since 2.7.0
    367458 *
    368459 * @param string $plugin Relative plugin path from Plugin Directory.
    … …  
    455546}
    456547
     548/**
     549 * Add sub menu page to the management main menu.
     550 *
     551 * @param string $page_title
     552 * @param unknown_type $menu_title
     553 * @param unknown_type $access_level
     554 * @param unknown_type $file
     555 * @param unknown_type $function
     556 * @return unknown
     557 */
    457558function add_management_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    458559    return add_submenu_page( 'edit.php', $page_title, $menu_title, $access_level, $file, $function );

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

    r8889 r8912  
    22
    33/**
    4  * _wp_translate_postdata() - Rename $_POST data from form names to DB post columns.
     4 * Rename $_POST data from form names to DB post columns.
    55 *
    66 * Manipulates $_POST directly.
    … …  
    196196        $text       = funky_javascript_fix( $text);
    197197        $popupurl   = clean_url($_REQUEST['popupurl']);
    198         $post_content = '<a href="'.$popupurl.'">'.$post_title.'</a>'."\n$text";
    199     }
     198        $post_content = '<a href="'.$popupurl.'">'.$post_title.'</a>'."\n$text";
     199    }
    200200
    201201    if ( !empty( $_REQUEST['excerpt'] ) )
    … …  
    227227
    228228function get_default_page_to_edit() {
    229     $page = get_default_post_to_edit();
    230     $page->post_type = 'page';
    231     return $page;
     229    $page = get_default_post_to_edit();
     230    $page->post_type = 'page';
     231    return $page;
    232232}
    233233

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

    r8700 r8912  
    11<?php
    2 
    3 // $_search is unsanitized
     2/**
     3 * WordPress Widgets Administration API
     4 *
     5 * @package WordPress
     6 * @subpackage Administration
     7 */
     8
     9/**
     10 * Display list of widgets, either all or matching search.
     11 *
     12 * @since unknown
     13 *
     14 * @param unknown_type $show
     15 * @param unknown_type $_search Optional. Search for widgets. Should be unsanitized.
     16 */
    417function wp_list_widgets( $show = 'all', $_search = false ) {
    518    global $wp_registered_widgets, $sidebars_widgets, $wp_registered_widget_controls;
    … …  
    149162}
    150163
    151 
    152 
     164/**
     165 * {@internal Missing Short Description}}
     166 *
     167 * @since unknown
     168 *
     169 * @param unknown_type $sidebar
     170 */
    153171function wp_list_widget_controls( $sidebar ) {
    154172    add_filter( 'dynamic_sidebar_params', 'wp_list_widget_controls_dynamic_sidebar' );
    … …  
    164182}
    165183
    166 
     184/**
     185 * {@internal Missing Short Description}}
     186 *
     187 * @since unknown
     188 *
     189 * @param unknown_type $params
     190 * @return unknown
     191 */
    167192function wp_list_widget_controls_dynamic_sidebar( $params ) {
    168193    global $wp_registered_widgets;
    … …  
    183208}
    184209
    185 /*
    186  * Meta widget used to display the control form for a widget.  Called from dynamic_sidebar()
     210/**
     211 * Meta widget used to display the control form for a widget.
     212 *
     213 * Called from dynamic_sidebar().
     214 *
     215 * @since unknown
     216 *
     217 * @param unknown_type $sidebar_args
     218 * @return unknown
    187219 */
    188220function wp_widget_control( $sidebar_args ) {
    … …  
    277309}
    278310
     311/**
     312 * {@internal Missing Short Description}}
     313 *
     314 * @since unknown
     315 *
     316 * @param unknown_type $string
     317 * @return unknown
     318 */
    279319function wp_widget_control_ob_filter( $string ) {
    280320    if ( false === $beg = strpos( $string, '%BEG_OF_TITLE%' ) )
Note: See TracChangeset for help on using the changeset viewer.