From 15bc3416965b28c64d815752591d7a1b22b8d388 Mon Sep 17 00:00:00 2001 From: nacin Date: Sun, 5 Sep 2010 02:45:39 +0000 Subject: [PATCH] phpdoc, @since, whitespace. Also require an argument in wp_insert_post(). props duck_, see #14783. git-svn-id: http://svn.automattic.com/wordpress/trunk@15564 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/admin-ajax.php | 2 +- wp-admin/custom-background.php | 2 +- wp-admin/includes/bookmark.php | 87 ++++++++++++++++---------------- wp-admin/includes/comment.php | 25 +++++---- wp-admin/includes/dashboard.php | 30 +++++------ wp-includes/general-template.php | 4 +- wp-includes/post.php | 13 ++--- wp-includes/wp-db.php | 1 - 8 files changed, 79 insertions(+), 85 deletions(-) diff --git a/wp-admin/admin-ajax.php b/wp-admin/admin-ajax.php index a79b1881b..30162a7de 100644 --- a/wp-admin/admin-ajax.php +++ b/wp-admin/admin-ajax.php @@ -9,7 +9,7 @@ /** * Executing AJAX process. * - * @since unknown + * @since 2.1.0 */ define('DOING_AJAX', true); define('WP_ADMIN', true); diff --git a/wp-admin/custom-background.php b/wp-admin/custom-background.php index 413c564fd..9b0102f6c 100644 --- a/wp-admin/custom-background.php +++ b/wp-admin/custom-background.php @@ -311,7 +311,7 @@ if ( get_background_image() ) { } /** - * Handle a Image upload for the background image. + * Handle an Image upload for the background image. * * @since 3.0.0 */ diff --git a/wp-admin/includes/bookmark.php b/wp-admin/includes/bookmark.php index 09e5411e5..6b5aab784 100644 --- a/wp-admin/includes/bookmark.php +++ b/wp-admin/includes/bookmark.php @@ -7,27 +7,27 @@ */ /** - * {@internal Missing Short Description}} + * Add a link to using values provided in $_POST. * - * @since unknown + * @since 2.0.0 * - * @return unknown + * @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success. */ function add_link() { return edit_link(); } /** - * {@internal Missing Short Description}} + * Update or insert a link using values provided in $_POST. * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $link_id - * @return unknown + * @param int $link_id Optional. ID of the link to edit. + * @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success. */ -function edit_link( $link_id = '' ) { - if (!current_user_can( 'manage_links' )) - wp_die( __( 'Cheatin’ uh?' )); +function edit_link( $link_id = 0 ) { + if ( !current_user_can( 'manage_links' ) ) + wp_die( __( 'Cheatin’ uh?' ) ); $_POST['link_url'] = esc_html( $_POST['link_url'] ); $_POST['link_url'] = esc_url($_POST['link_url']); @@ -39,27 +39,27 @@ function edit_link( $link_id = '' ) { if ( !empty( $link_id ) ) { $_POST['link_id'] = $link_id; - return wp_update_link( $_POST); + return wp_update_link( $_POST ); } else { - return wp_insert_link( $_POST); + return wp_insert_link( $_POST ); } } /** - * {@internal Missing Short Description}} + * Retrieve the default link for editing. * - * @since unknown + * @since 2.0.0 * - * @return unknown + * @return object Default link */ function get_default_link_to_edit() { if ( isset( $_GET['linkurl'] ) ) - $link->link_url = esc_url( $_GET['linkurl']); + $link->link_url = esc_url( $_GET['linkurl'] ); else $link->link_url = ''; if ( isset( $_GET['name'] ) ) - $link->link_name = esc_attr( $_GET['name']); + $link->link_name = esc_attr( $_GET['name'] ); else $link->link_name = ''; @@ -69,12 +69,12 @@ function get_default_link_to_edit() { } /** - * {@internal Missing Short Description}} + * Delete link specified from database * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $link_id - * @return unknown + * @param int $link_id ID of the link to delete + * @return bool True */ function wp_delete_link( $link_id ) { global $wpdb; @@ -93,12 +93,12 @@ function wp_delete_link( $link_id ) { } /** - * {@internal Missing Short Description}} + * Retrieves the link categories associated with the link specified. * - * @since unknown + * @since 2.1.0 * - * @param unknown_type $link_id - * @return unknown + * @param int $link_id Link ID to look up + * @return array The requested link's categories */ function wp_get_link_cats( $link_id = 0 ) { @@ -108,24 +108,25 @@ function wp_get_link_cats( $link_id = 0 ) { } /** - * {@internal Missing Short Description}} + * Retrieve link data based on ID. * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $link_id - * @return unknown + * @param int $link_id ID of link to retrieve + * @return object Link for editing */ function get_link_to_edit( $link_id ) { return get_bookmark( $link_id, OBJECT, 'edit' ); } /** - * {@internal Missing Short Description}} + * This function inserts/updates links into/in the database. * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $linkdata - * @return unknown + * @param array $linkdata Elements that make up the link to insert. + * @param bool $wp_error Optional. If true return WP_Error object on failure. + * @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success. */ function wp_insert_link( $linkdata, $wp_error = false ) { global $wpdb; @@ -181,7 +182,7 @@ function wp_insert_link( $linkdata, $wp_error = false ) { $link_rel = ''; // Make sure we set a valid category - if ( ! isset( $link_category ) ||0 == count( $link_category ) || !is_array( $link_category ) ) { + if ( ! isset( $link_category ) || 0 == count( $link_category ) || !is_array( $link_category ) ) { $link_category = array( get_option( 'default_link_category' ) ); } @@ -215,12 +216,12 @@ function wp_insert_link( $linkdata, $wp_error = false ) { } /** - * {@internal Missing Short Description}} + * Update link with the specified link categories. * - * @since unknown + * @since 2.1.0 * - * @param unknown_type $link_id - * @param unknown_type $link_categories + * @param int $link_id ID of link to update + * @param array $link_categories Array of categories to */ function wp_set_link_cats( $link_id = 0, $link_categories = array() ) { // If $link_categories isn't already an array, make it one: @@ -233,15 +234,15 @@ function wp_set_link_cats( $link_id = 0, $link_categories = array() ) { wp_set_object_terms( $link_id, $link_categories, 'link_category' ); clean_bookmark_cache( $link_id ); -} // wp_set_link_cats() +} /** - * {@internal Missing Short Description}} + * Update a link in the database. * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $linkdata - * @return unknown + * @param array $linkdata Link data to update. + * @return int|WP_Error Value 0 or WP_Error on failure. The updated link ID on success. */ function wp_update_link( $linkdata ) { $link_id = (int) $linkdata['link_id']; diff --git a/wp-admin/includes/comment.php b/wp-admin/includes/comment.php index f9b97798f..74ffa3813 100644 --- a/wp-admin/includes/comment.php +++ b/wp-admin/includes/comment.php @@ -9,11 +9,11 @@ /** * {@internal Missing Short Description}} * - * @since unknown + * @since 2.0.0 * @uses $wpdb * - * @param string $comment_author - * @param string $comment_date + * @param string $comment_author Author of the comment + * @param string $comment_date Date of the comment * @return mixed Comment ID on success. */ function comment_exists($comment_author, $comment_date) { @@ -27,16 +27,15 @@ function comment_exists($comment_author, $comment_date) { } /** - * {@internal Missing Short Description}} + * Update a comment with values provided in $_POST. * - * @since unknown + * @since 2.0.0 */ function edit_comment() { - $comment_post_ID = (int) $_POST['comment_post_ID']; if (!current_user_can( 'edit_post', $comment_post_ID )) - wp_die( __('You are not allowed to edit comments on this post, so you cannot edit this comment.' )); + wp_die( __('You are not allowed to edit comments on this post, so you cannot edit this comment.' ) ); $_POST['comment_author'] = $_POST['newcomment_author']; $_POST['comment_author_email'] = $_POST['newcomment_author_email']; @@ -52,7 +51,7 @@ function edit_comment() { } } - if (!empty ( $_POST['edit_date'] ) ) { + if ( !empty ( $_POST['edit_date'] ) ) { $aa = $_POST['aa']; $mm = $_POST['mm']; $jj = $_POST['jj']; @@ -66,16 +65,16 @@ function edit_comment() { $_POST['comment_date'] = "$aa-$mm-$jj $hh:$mn:$ss"; } - wp_update_comment( $_POST); + wp_update_comment( $_POST ); } /** * {@internal Missing Short Description}} * - * @since unknown + * @since 2.0.0 * - * @param unknown_type $id - * @return unknown + * @param int $id ID of comment to retrieve + * @return bool|object Comment if found. False on failure. */ function get_comment_to_edit( $id ) { if ( !$comment = get_comment($id) ) @@ -98,7 +97,7 @@ function get_comment_to_edit( $id ) { /** * Get the number of pending comments on a post or posts * - * @since unknown + * @since 2.3.0 * @uses $wpdb * * @param int|array $post_id Either a single Post ID or an array of Post IDs diff --git a/wp-admin/includes/dashboard.php b/wp-admin/includes/dashboard.php index c35be0a16..672fbd1cc 100644 --- a/wp-admin/includes/dashboard.php +++ b/wp-admin/includes/dashboard.php @@ -9,9 +9,9 @@ /** * Registers dashboard widgets. * - * handles POST data, sets up filters. + * Handles POST data, sets up filters. * - * @since unknown + * @since 2.5.0 */ function wp_dashboard_setup() { global $wp_registered_widgets, $wp_registered_widget_controls, $wp_dashboard_control_callbacks; @@ -150,7 +150,7 @@ function _wp_dashboard_control_callback( $dashboard, $meta_box ) { /** * Displays the dashboard. * - * @since unknown + * @since 2.5.0 */ function wp_dashboard() { global $screen_layout_columns; @@ -517,7 +517,7 @@ function wp_dashboard_recent_drafts( $drafts = false ) { /** * Display recent comments dashboard widget content. * - * @since unknown + * @since 2.5.0 */ function wp_dashboard_recent_comments() { global $wpdb; @@ -703,7 +703,7 @@ function wp_dashboard_incoming_links() { /** * Display incoming links dashboard widget content. * - * @since unknown + * @since 2.5.0 */ function wp_dashboard_incoming_links_output() { $widgets = get_option( 'dashboard_widget_options' ); @@ -795,9 +795,9 @@ function wp_dashboard_primary_control() { /** * {@internal Missing Short Description}} * - * @since unknown + * @since 2.5.0 * - * @param int $widget_id + * @param string $widget_id */ function wp_dashboard_rss_output( $widget_id ) { $widgets = get_option( 'dashboard_widget_options' ); @@ -817,7 +817,7 @@ function wp_dashboard_secondary_control() { /** * Display secondary dashboard RSS widget feed. * - * @since unknown + * @since 2.5.0 * * @return unknown */ @@ -852,7 +852,7 @@ function wp_dashboard_plugins() { /** * Display plugins most popular, newest plugins, and recently updated widget text. * - * @since unknown + * @since 2.5.0 */ function wp_dashboard_plugins_output() { $popular = fetch_feed( 'http://wordpress.org/extend/plugins/rss/browse/popular/' ); @@ -938,9 +938,9 @@ function wp_dashboard_plugins_output() { * echoes out output for this widget. If not cache, echo a "Loading..." stub * which is later replaced by AJAX call (see top of /wp-admin/index.php) * - * @since unknown + * @since 2.5.0 * - * @param int $widget_id + * @param string $widget_id * @param callback $callback * @param array $check_urls RSS feeds * @return bool False on failure. True on success. @@ -981,7 +981,7 @@ function wp_dashboard_cached_rss_widget( $widget_id, $callback, $check_urls = ar /** * Calls widget control callback. * - * @since unknown + * @since 2.5.0 * * @param int $widget_control_id Registered Widget ID. */ @@ -999,10 +999,10 @@ function wp_dashboard_trigger_widget_control( $widget_control_id = false ) { * Sets up $args to be used as input to wp_widget_rss_form(). Handles POST data * from RSS-type widgets. * - * @since unknown + * @since 2.5.0 * - * @param string widget_id - * @param array form_inputs + * @param string $widget_id + * @param array $form_inputs */ function wp_dashboard_rss_control( $widget_id, $form_inputs = array() ) { if ( !$widget_options = get_option( 'dashboard_widget_options' ) ) diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 3b2d3d804..5bed9212b 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -381,7 +381,7 @@ function bloginfo( $show='' ) { * * The possible values for the 'show' parameter are listed below. *
    - *
  1. url - Blog URI to homepage.
    2. + *
  2. url - Blog URI to homepage.
    3. *
  3. wpurl - Blog URI path to WordPress.
    4. *
  4. description - Secondary title
    5. *
@@ -1318,7 +1318,7 @@ function the_date_xml() { * * Will only output the date if the current post's date is different from the * previous one output. - + * * i.e. Only one date listing will show per day worth of posts shown in the loop, even if the * function is called several times for each post. * diff --git a/wp-includes/post.php b/wp-includes/post.php index cab70ced0..0da73c419 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -2125,25 +2125,20 @@ function wp_get_single_post($postid = 0, $mode = OBJECT) { * 'post_excerpt' - Post excerpt. * * @since 1.0.0 - * @link http://core.trac.wordpress.org/ticket/9084 Bug report on 'wp_insert_post_data' filter. * @uses $wpdb * @uses $wp_rewrite * @uses $user_ID - * * @uses do_action() Calls 'pre_post_update' on post ID if this is an update. * @uses do_action() Calls 'edit_post' action on post ID and post data if this is an update. - * @uses do_action() Calls 'save_post' and 'wp_insert_post' on post id and post data just before - * returning. - * - * @uses apply_filters() Calls 'wp_insert_post_data' passing $data, $postarr prior to database - * update or insert. + * @uses do_action() Calls 'save_post' and 'wp_insert_post' on post id and post data just before returning. + * @uses apply_filters() Calls 'wp_insert_post_data' passing $data, $postarr prior to database update or insert. * @uses wp_transition_post_status() * - * @param array $postarr Optional. Overrides defaults. + * @param array $postarr Elements that make up post to insert. * @param bool $wp_error Optional. Allow return of WP_Error on failure. * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success. */ -function wp_insert_post($postarr = array(), $wp_error = false) { +function wp_insert_post($postarr, $wp_error = false) { global $wpdb, $wp_rewrite, $user_ID; $defaults = array('post_status' => 'draft', 'post_type' => 'post', 'post_author' => $user_ID, diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index cbe27483f..818cd3fa3 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -48,7 +48,6 @@ define( 'ARRAY_N', 'ARRAY_N' ); * @package WordPress * @subpackage Database * @since 0.71 - * @final */ class wpdb {