Ticket #2473: functions-post.diff

functions-post.php

@@ -2 +2 @@
 
 /**** DB Functions ****/
 
-/*
- * generic function for inserting data into the posts table.
+/**
+ * Insert or update data in the posts table
+ * @param       array   $postarr        an array of the POSTed data from the Write screen
+ * @return      int     the post_ID of the inserted or updated post
  */
 function wp_insert_post($postarr = array()) {
         global $wpdb, $wp_rewrite, $allowedtags, $user_ID;
@@ -219 +221 @@
         return $post_ID;
 }
 
+/**
+ * Insert or update an attachment to a post
+ * @param       object  $object        an object of postdata
+ * @param       bool    $file           whether to set the _wp_attached_file postmeta for this post
+ * @param       int     $post_parent    the post_ID of the parent element to this post
+ * @return      int     the post_ID of the inserted or updated post
+*/
 function wp_insert_attachment($object, $file = false, $post_parent = 0) {
         global $wpdb, $user_ID;
 
@@ -359 +368 @@
         return $post_ID;
 }
 
+/**
+ * Remove an attachment, and delete any associated on-disk files (including thumbnails)
+ * @param       int     $postid         the post_ID of the attachment to remove
+ * @return      mixed                   the post object from which the attachment was deleted, or boolean false on error
+*/
+   
 function wp_delete_attachment($postid) {
         global $wpdb;
         $postid = (int) $postid;
@@ -394 +409 @@
         return $post;
 }
 
+/**
+ * Select a single post from the database and includes the categories to which that post belongs
+ * @param       int      $postid        the post_ID of the post to return
+ * @param       constant $mode          Whether to return an OBJECT or an ARRAY
+ * @return      mixed                   returns either an OBJECT or an ARRAY, as defined by $mode
+*/
 function wp_get_single_post($postid = 0, $mode = OBJECT) {
         global $wpdb;
 
@@ -410 +431 @@
         return $post;
 }
 
+**
+ * Return some number of recent posts
+ * @param       int     $num    the number of posts to return
+ * @return      array           returns an array of posts sorted descending by date, or an empty array in case of failure
+*/
+  
 function wp_get_recent_posts($num = 10) {
         global $wpdb;
 
@@ -424 +451 @@
         return $result?$result:array();
 }
 
+**
+ * Update a post
+ * @param       array   $postarr        the post data to update
+ * @return      int                     returns the post_ID of the updated post (as returned by wp_insert_post())
+*/  
 function wp_update_post($postarr = array()) {
         global $wpdb;
 
@@ -464 +496 @@
         return wp_insert_post($postarr);
 }
 
+**
+ * Sets a post's status to "publish"
+ * @param       int     $post_id        The post_ID of the post to publish
+ * @return      int                     Returns the post_ID of the published post, or null if no change was performed
+*/
 function wp_publish_post($post_id) {
         $post = get_post($post_id);
 
@@ -476 +513 @@
         return wp_update_post(array('post_status' => 'publish', 'ID' => $post_id));     
 }
 
+/**
+ * Returns an array of categories to which a specific post is assigned
+ * @param       int     $blogid         The ID of the blog that owns the post (used only for WPMU)
+ * @param       int     $post_ID        the post_ID of the post who's categories are being selected
+ * @return      array                   returns an array of category IDs
+*/
 function wp_get_post_cats($blogid = '1', $post_ID = 0) {
         global $wpdb;
 
@@ -492 +535 @@
         return array_unique($result);
 }
 
+/**
+ *
+ * @param       int     $blogid         the ID of the blog (used for WPMU)
+ * @param       int     $post_ID        the post_ID for the post who's categories are being set
+ * @param       array   $post_categories        an array of categories to which the post will be assigned
+ * @return      none
+*/
 function wp_set_post_cats($blogid = '1', $post_ID = 0, $post_categories = array()) {
         global $wpdb;
         // If $post_categories isn't already an array, make it one:
@@ -545 +595 @@
         }
 }       // wp_set_post_cats()
 
+/**
+ * Delete a post from the database
+ * @param       int     $post_id        the post_id of the post to delete
+ * @return      mixed                   an object containing the contents of the deleted post, or boolean false if nothing was deleted
+*/
 function wp_delete_post($postid = 0) {
         global $wpdb, $wp_rewrite;
         $postid = (int) $postid;