Changeset 19753

Timestamp:

01/25/2012 09:58:23 PM (13 years ago)

Author:

duck_

Message:

Improve the inline documentation of rewrite endpoints. See #16303.

File:

• trunk/wp-includes/rewrite.php (modified) (3 diffs)

trunk/wp-includes/rewrite.php

@@ -102 +102 @@
 }
 
-//pseudo-places
 /**
  * Endpoint Mask for default, which is nothing.
@@ -211 +210 @@
  * Add an endpoint, like /trackback/.
  *
- * The endpoints are added to the end of the request. So a request matching
- * "/2008/10/14/my_post/myep/", the endpoint will be "/myep/".
- *
- * Be sure to flush the rewrite rules (wp_rewrite->flush_rules()) when your plugin gets
- * activated (register_activation_hook()) and deactivated (register_deactivation_hook())
+ * Adding an endpoint creates extra rewrite rules for each of the matching
+ * places specified by the provided bitmask. For example:
+ *
+ * <code>
+ * add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );
+ * </code>
+ *
+ * will add a new rewrite rule ending with "json(/(.*))?/?$" for every permastruct
+ * that describes a permalink (post) or page. This is rewritten to "json=$match"
+ * where $match is the part of the URL matched by the endpoint regex (e.g. "foo" in
+ * "<permalink>/json/foo/").
+ *
+ * A new query var with the same name as the endpoint will also be created.
+ *
+ * When specifying $places ensure that you are using the EP_* constants (or a
+ * combination of them using the bitwise OR operator) as their values are not
+ * guaranteed to remain static (especially EP_ALL).
+ *
+ * Be sure to flush the rewrite rules - flush_rewrite_rules() - when your plugin gets
+ * activated and deactivated.
  *
  * @since 2.1.0
- * @see WP_Rewrite::add_endpoint() Parameters and more description.
- * @uses $wp_rewrite
- *
- * @param unknown_type $name
- * @param unknown_type $places
- */
-function add_rewrite_endpoint($name, $places) {
+ * @see WP_Rewrite::add_endpoint()
+ * @global object $wp_rewrite
+ *
+ * @param string $name Name of the endpoint.
+ * @param int $places Endpoint mask describing the places the endpoint should be added.
+ */
+function add_rewrite_endpoint( $name, $places ) {
     global $wp_rewrite;
-    $wp_rewrite->add_endpoint($name, $places);
+    $wp_rewrite->add_endpoint( $name, $places );
 }
 
@@ -1834 +1848 @@
      * Add an endpoint, like /trackback/.
      *
-     * To be inserted after certain URL types (specified in $places).
-     *
+     * See {@link add_rewrite_endpoint()} for full documentation.
+     *
+     * @see add_rewrite_endpoint()
      * @since 2.1.0
      * @access public
-     *
-     * @param string $name Name of endpoint.
-     * @param array $places URL types that endpoint can be used.
+     * @uses WP::add_query_var()
+     *
+     * @param string $name Name of the endpoint.
+     * @param int $places Endpoint mask describing the places the endpoint should be added.
      */
     function add_endpoint($name, $places) {