From a9571e003a41d5bd409972229804619decac338a Mon Sep 17 00:00:00 2001
From: westi <westi@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Sat, 14 Jun 2008 16:31:08 +0000
Subject: [PATCH] PHPdoc updates for wp-includes/post.php. See #7038 props
 jacobsantos.

git-svn-id: http://svn.automattic.com/wordpress/trunk@8081 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/post.php | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/wp-includes/post.php b/wp-includes/post.php
index 5c9409ad02..221f84f272 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -1,6 +1,10 @@
 <?php
 /**
- * Post functions and post utility function
+ * Post functions and post utility function.
+ *
+ * Warning: The inline documentation for the functions contained
+ * in this file might be inaccurate, so the documentation is not
+ * authoritative at the moment.
  *
  * @package WordPress
  * @subpackage Post
@@ -750,16 +754,26 @@ function sanitize_post_field($field, $value, $post_id, $context) {
 }
 
 /**
- * wp_count_posts() - Count number of posts with a given type
+ * Count number of posts of a post type and is permissible.
  *
- * {@internal Missing Long Description}}
+ * This function provides an efficient method of finding the amount
+ * of post's type a blog has. Another method is to count the amount
+ * of items in get_posts(), but that method has a lot of overhead
+ * with doing so. Therefore, when developing for 2.5+, use this
+ * function instead.
+ *
+ * The $perm parameter checks for 'readable' value and if the user
+ * can read private posts, it will display that for the user that
+ * is signed in.
  *
  * @package WordPress
  * @subpackage Post
  * @since 2.5
+ * @link http://codex.wordpress.org/Template_Tags/wp_count_posts
  *
- * @param string $type Post type
- * @return array Number of posts for each status
+ * @param string $type Optional. Post type to retrieve count
+ * @param string $perm Optional. 'readable' or empty.
+ * @return object Number of posts for each status
  */
 function wp_count_posts( $type = 'post', $perm = '' ) {
 	global $wpdb;