Index: trunk/wp-includes/rewrite.php
===================================================================
--- trunk/wp-includes/rewrite.php	(revision 8899)
+++ trunk/wp-includes/rewrite.php	(revision 8924)
@@ -192,15 +192,15 @@
 
 /**
-  * Filter the URL base for taxonomies.
-  *
-  * To remove any manually prepended /index.php/.
-  *
-  * @access private
-  * @since unknown (2.3.0?)
-  * @author Mark Jaquith
-  *
-  * @param string $base The taxonomy base that we're going to filter
-  * @return string
-  */
+ * Filter the URL base for taxonomies.
+ *
+ * To remove any manually prepended /index.php/.
+ *
+ * @access private
+ * @since 2.6.0
+ * @author Mark Jaquith
+ *
+ * @param string $base The taxonomy base that we're going to filter
+ * @return string
+ */
 function _wp_filter_taxonomy_base( $base ) {
 	if ( !empty( $base ) ) {
@@ -482,6 +482,6 @@
 	 * The difference between the root property is that WordPress might be
 	 * located at example/WordPress/index.php, if permalinks are turned off. The
-	 * index.php will be the front portion. If permalinks are turned on, this
-	 * will most likely be empty or not set.
+	 * WordPress/index.php will be the front portion. If permalinks are turned
+	 * on, this will most likely be empty or not set.
 	 *
 	 * @since 1.5.0
@@ -513,5 +513,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Request match string.
 	 *
 	 * @since 1.5.0
@@ -553,5 +553,7 @@
 
 	/**
-	 * Rules that don't redirect to WP's index.php
+	 * Rules that don't redirect to WP's index.php.
+	 *
+	 * These rules are written to the mod_rewrite portion of the .htaccess.
 	 *
 	 * @since 2.1.0
@@ -562,5 +564,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Extra permalink structures.
 	 *
 	 * @since 2.1.0
@@ -580,5 +582,8 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Whether to write every mod_rewrite rule for WordPress.
+	 *
+	 * This is off by default, turning it on might print a lot of rewrite rules
+	 * to the .htaccess file.
 	 *
 	 * @since 2.0.0
@@ -589,5 +594,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Whether to write every mod_rewrite rule for WordPress pages.
 	 *
 	 * @since 2.5.0
@@ -598,5 +603,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Permalink structure search for preg_replace.
 	 *
 	 * @since 1.5.0
@@ -622,5 +627,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Preg_replace values for the search, see {@link WP_Rewrite::$rewritecode}.
 	 *
 	 * @since 1.5.0
@@ -646,5 +651,5 @@
 
 	/**
-	 * {@internal Missing Description}}
+	 * Search for the query to look for replacing.
 	 *
 	 * @since 1.5.0
@@ -736,7 +741,12 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
+	 * Index for matches for usage in preg_*() functions.
+	 *
+	 * The format of the string is, with empty matches property value, '$NUM'.
+	 * The 'NUM' will be replaced with the value in the $number parameter. With
+	 * the matches property not empty, the value of the returned string will
+	 * contain that value of the matches property. The format then will be
+	 * '$MATCHES[NUM]', with MATCHES as the value in the property and NUM the
+	 * value of the $number parameter.
 	 *
 	 * @since 1.5.0
@@ -750,5 +760,5 @@
 		$match_suffix = '';
 
-		if (! empty($this->matches)) {
+		if ( ! empty($this->matches) ) {
 			$match_prefix = '$' . $this->matches . '[';
 			$match_suffix = ']';
@@ -759,12 +769,13 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
+	 * Retrieve all page and attachments for pages URIs.
+	 *
+	 * The attachments are for those that have pages as parents and will be
+	 * retrieved.
 	 *
 	 * @since 2.5.0
 	 * @access public
 	 *
-	 * @return unknown
+	 * @return array Array of page URIs as first element and attachment URIs as second element.
 	 */
 	function page_uri_index() {
@@ -781,5 +792,4 @@
 		if ( !$posts )
 			return array( array(), array() );
-
 
 		foreach ($posts as $id => $post) {
@@ -801,12 +811,15 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @return unknown
+	 * Retrieve all of the rewrite rules for pages.
+	 *
+	 * If the 'use_verbose_page_rules' property is false, then there will only
+	 * be a single rewrite rule for pages for those matching '%pagename%'. With
+	 * the property set to true, the attachments and the pages will be added for
+	 * each individual attachment URI and page URI, respectively.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @return array
 	 */
 	function page_rewrite_rules() {
@@ -823,5 +836,4 @@
 		$uris = $page_uris[0];
 		$attachment_uris = $page_uris[1];
-
 
 		if( is_array( $attachment_uris ) ) {
@@ -973,5 +985,8 @@
 	 * Retrieve the permalink structure for categories.
 	 *
-	 * {@internal Missing Long Description}}
+	 * If the category_base property has no value, then the category structure
+	 * will have the front property value, followed by 'category', and finally
+	 * '%category%'. If it does, then the root property will be used, along with
+	 * the category_base property value.
 	 *
 	 * @since 1.5.0
@@ -1003,5 +1018,8 @@
 	 * Retrieve the permalink structure for tags.
 	 *
-	 * {@internal Missing Long Description}}
+	 * If the tag_base property has no value, then the tag structure will have
+	 * the front property value, followed by 'tag', and finally '%tag%'. If it
+	 * does, then the root property will be used, along with the tag_base
+	 * property value.
 	 *
 	 * @since 2.3.0
@@ -1181,21 +1199,23 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @param unknown_type $tag
-	 * @param unknown_type $pattern
-	 * @param unknown_type $query
+	 * Append or update tag, pattern, and query for replacement.
+	 *
+	 * If the tag already exists, replace the existing pattern and query for
+	 * that tag, otherwise add the new tag, pattern, and query to the end of the
+	 * arrays.
+	 *
+	 * @internal What is the purpose of this function again? Need to finish long
+	 *           description.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @param string $tag Append tag to rewritecode property array.
+	 * @param string $pattern Append pattern to rewritereplace property array.
+	 * @param string $query Append query to queryreplace property array.
 	 */
 	function add_rewrite_tag($tag, $pattern, $query) {
-		// If the tag already exists, replace the existing pattern and query for
-		// that tag, otherwise add the new tag, pattern, and query to the end of
-		// the arrays.
 		$position = array_search($tag, $this->rewritecode);
-		if (FALSE !== $position && NULL !== $position) {
+		if ( false !== $position && null !== $position ) {
 			$this->rewritereplace[$position] = $pattern;
 			$this->queryreplace[$position] = $query;
@@ -1210,19 +1230,19 @@
 	 * Generate the rules from permalink structure.
 	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * The main WP_Rewrite function.
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @param unknown_type $permalink_structure
-	 * @param unknown_type $ep_mask
-	 * @param unknown_type $paged
-	 * @param unknown_type $feed
-	 * @param unknown_type $forcomments
-	 * @param unknown_type $walk_dirs
-	 * @param unknown_type $endpoints
-	 * @return unknown
+	 * The main WP_Rewrite function for building the rewrite rule list. The
+	 * contents of the function is a mix of black magic and regular expressions,
+	 * so best just ignore the contents and move to the parameters.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @param string $permalink_structure The permalink structure.
+	 * @param int $ep_mask Optional, default is EP_NONE. Endpoint constant, see EP_* constants.
+	 * @param bool $paged Optional, default is true. Whether permalink request is paged.
+	 * @param bool $feed Optional, default is true. Whether for feed.
+	 * @param bool $forcomments Optional, default is false. Whether for comments.
+	 * @param bool $walk_dirs Optional, default is true. Whether to create list of directories to walk over.
+	 * @param bool $endpoints Optional, default is true. Whether endpoints are enabled.
+	 * @return array Rewrite rule list.
 	 */
 	function generate_rewrite_rules($permalink_structure, $ep_mask = EP_NONE, $paged = true, $feed = true, $forcomments = false, $walk_dirs = true, $endpoints = true) {
@@ -1443,14 +1463,17 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @param unknown_type $permalink_structure
-	 * @param unknown_type $walk_dirs
-	 * @return unknown
+	 * Generate Rewrite rules with permalink structure and walking directory only.
+	 *
+	 * Shorten version of {@link WP_Rewrite::generate_rewrite_rules()} that
+	 * allows for shorter list of parameters. See the method for longer
+	 * description of what generating rewrite rules does.
+	 *
+	 * @uses WP_Rewrite::generate_rewrite_rules() See for long description and rest of parameters.
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @param string $permalink_structure The permalink structure to generate rules.
+	 * @param bool $walk_dirs Optional, default is false. Whether to create list of directories to walk over.
+	 * @return array
 	 */
 	function generate_rewrite_rule($permalink_structure, $walk_dirs = false) {
@@ -1459,12 +1482,20 @@
 
 	/**
-	 * Construct rewrite matches and queries from permalink structure
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @return array an associate array of matches and queries
+	 * Construct rewrite matches and queries from permalink structure.
+	 *
+	 * Runs the action 'generate_rewrite_rules' with the parameter that is an
+	 * reference to the current WP_Rewrite instance to further manipulate the
+	 * permalink structures and rewrite rules. Runs the 'rewrite_rules_array'
+	 * filter on the full rewrite rule array.
+	 *
+	 * There are two ways to manipulate the rewrite rules, one by hooking into
+	 * the 'generate_rewrite_rules' action and gaining full control of the
+	 * object or just manipulating the rewrite rule array before it is passed
+	 * from the function.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @return array An associate array of matches and queries.
 	 */
 	function rewrite_rules() {
@@ -1540,12 +1571,16 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @return unknown
+	 * Retrieve the rewrite rules.
+	 *
+	 * The difference between this method and {@link
+	 * WP_Rewrite::rewrite_rules()} is that this method stores the rewrite rules
+	 * in the 'rewrite_rules' option and retrieves it. This prevents having to
+	 * process all of the permalinks to get the rewrite rules in the form of
+	 * caching.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @return array Rewrite rules.
 	 */
 	function wp_rewrite_rules() {
@@ -1561,12 +1596,16 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * @since 1.5.0
-	 * @access public
-	 *
-	 * @return unknown
+	 * Retrieve mod_rewrite formatted rewrite rules to write to .htaccess.
+	 *
+	 * Does not actually write to the .htaccess file, but creates the rules for
+	 * the process that will.
+	 *
+	 * Will add  the non_wp_rules property rules to the .htaccess file before
+	 * the WordPress rewrite rules one.
+	 *
+	 * @since 1.5.0
+	 * @access public
+	 *
+	 * @return string
 	 */
 	function mod_rewrite_rules() {
@@ -1638,14 +1677,15 @@
 
 	/**
-	 * Add a straight rewrite rule
-	 *
-	 * {@internal Missing Long Description}}
+	 * Add a straight rewrite rule.
+	 *
+	 * Any value in the $after parameter that isn't 'bottom' will be placed at
+	 * the top of the rules.
 	 *
 	 * @since 2.1.0
 	 * @access public
 	 *
-	 * @param unknown_type $regex
-	 * @param unknown_type $redirect
-	 * @param unknown_type $after
+	 * @param string $regex Regular expression to match against request.
+	 * @param string $redirect URL regex redirects to when regex matches request.
+	 * @param string $after Optional, default is bottom. Location to place rule.
 	 */
 	function add_rule($regex, $redirect, $after = 'bottom') {
@@ -1665,13 +1705,13 @@
 
 	/**
-	 * Add a rule that doesn't redirect to index.php
-	 *
-	 * {@internal Missing Long Description}}
+	 * Add a rule that doesn't redirect to index.php.
+	 *
+	 * Can redirect to any place.
 	 *
 	 * @since 2.1.0
 	 * @access public
 	 *
-	 * @param unknown_type $regex
-	 * @param unknown_type $redirect
+	 * @param string $regex Regular expression to match against request.
+	 * @param string $redirect URL regex redirects to when regex matches request.
 	 */
 	function add_external_rule($regex, $redirect) {
@@ -1680,15 +1720,13 @@
 
 	/**
-	 * Add an endpoint, like /trackback/
-	 *
-	 * {@internal Missing Long Description}}
-	 *
-	 * To be inserted after certain URL types (specified in $places)
+	 * Add an endpoint, like /trackback/.
+	 *
+	 * To be inserted after certain URL types (specified in $places).
 	 *
 	 * @since 2.1.0
 	 * @access public
 	 *
-	 * @param unknown_type $name
-	 * @param unknown_type $places
+	 * @param string $name Name of endpoint.
+	 * @param array $places URL types that endpoint can be used.
 	 */
 	function add_endpoint($name, $places) {
@@ -1699,14 +1737,15 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
+	 * Add permalink structure.
+	 *
+	 * These are added along with the extra rewrite rules that are merged to the
+	 * top.
 	 *
 	 * @since unknown
 	 * @access public
 	 *
-	 * @param unknown_type $name
-	 * @param unknown_type $struct
-	 * @param unknown_type $with_front
+	 * @param string $name Name for permalink structure.
+	 * @param string $struct Permalink structure.
+	 * @param bool $with_front Prepend front base to permalink structure.
 	 */
 	function add_permastruct($name, $struct, $with_front = true) {
@@ -1734,7 +1773,9 @@
 
 	/**
-	 * {@internal Missing Short Description}}
-	 *
-	 * {@internal Missing Long Description}}
+	 * Sets up the object's properties.
+	 *
+	 * The 'use_verbose_page_rules' object property will be turned on, if the
+	 * permalink structure includes the following: '%postname%', '%category%',
+	 * '%tag%', or '%author%'.
 	 *
 	 * @since 1.5.0
