Update docs for router

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329534 c90b9560-bf6c-de11-be94-00142212c4b1

reference/yaf/yaf-controller-abstract.xml

@@ -23,7 +23,7 @@
    <para>
     You will find that you can not define __construct function for your custom
     controller, thus, <classname>Yaf_Controller_Abstract</classname> provides
-    a magic method: Yaf_Controller_Abstract::init().
+    a magic method: <methodname>Yaf_Controller_Abstract::init</methodname>.
    </para>
    <para>
     If you have defined a init() method in your custom controller, it will be
@@ -33,8 +33,14 @@
     Action may have arguments, when a request coming, if there are the same
     name variable in the request parameters(see
     <methodname>Yaf_Request_Abstract::getParam</methodname>) after routed, 
-    Yaf will pass them to the action method(see
-    <methodname>Yaf_Action_Abstract::execute</methodname>).
+    Yaf will pass them to the action method
+    (see <methodname>Yaf_Action_Abstract::execute</methodname>).
+    <note>
+     <para>
+      These arguments are directly fetched without filtering, it should be 
+      carefully processed before use them.
+     </para>
+    </note>
    </para>
   </section>
 <!-- }}} -->
@@ -116,6 +122,7 @@ class IndexController extends Yaf_Controller_Abstract {
 
     /* action method may have arguments */
     public indexAction($name, $id) {
+       /* $name and $id are unsafe raw data */
        assert($name == $this->getRequest()->getParam("name"));
        assert($id   == $this->_request->getParam("id"));
     }
@@ -152,21 +159,25 @@ class DummyAction extends Yaf_Action_Abstract {
     <varlistentry xml:id="yaf-controller-abstract.props.name">
      <term><varname>_name</varname></term>
      <listitem>
-      <para></para>
+      <para>
+        controller name
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="yaf-controller-abstract.props.request">
      <term><varname>_request</varname></term>
      <listitem>
       <para>
-      the request object
+      current request object
       </para>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="yaf-controller-abstract.props.response">
      <term><varname>_response</varname></term>
      <listitem>
-      <para></para>
+      <para>
+      current response object
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="yaf-controller-abstract.props.invoke-args">

reference/yaf/yaf-route-map.xml

@@ -12,7 +12,22 @@
   <section xml:id="yaf-route-map.intro">
    &reftitle.intro;
    <para>
+     <classname>Yaf_Route_Map</classname> is a built-in route, it simply
+     convert a URI endpoint (that part of the URI which comes after the
+     base URI: see <methodname>Yaf_Request_Abstract::setBaseUri</methodname>)
+     to a controller name or action name(depends on the paramter passed to
+     <methodname>Yaf_Route_Map::__construct</methodname>) in following rule:
+     A => controller A.
+     A/B/C => controller A_B_C.
+     A/B/C/D/E => controller A_B_C_D_E.
+    </para>
 
+    <para>
+     If the second parameter of
+     <methodname>Yaf_Route_Map::__construct</methodname> is specificed, then
+     only the part before delimeter of URI will used to routing, the part after
+     it is used to routing request parameters (see the example section of
+     <methodname>Yaf_Route_Map::__construct</methodname>).
    </para>
   </section>
 <!-- }}} -->

reference/yaf/yaf-route-static.xml

@@ -21,9 +21,9 @@
    </para>
    <para>
      please *NOTE* that it is unecessary to instance a <classname>Yaf_Route_Static</classname>, also 
-     unecesary to add it into <classname>Yaf_Router</classname>'s route stack,
-     since there is always be one in <classname>Yaf_Router</classname>'s route
-     stack, and always be called at the last time.
+     unecesary to add it into <classname>Yaf_Router</classname>'s routes stack,
+     since there is always be one in <classname>Yaf_Router</classname>'s
+     routes stack, and always be called at the last time.
    </para>
   </section>
 <!-- }}} -->

reference/yaf/yaf-router.xml

@@ -14,13 +14,13 @@
    <para>
    <classname>Yaf_Router</classname> is the standard framework router. Routing is
    the process of taking a URI endpoint (that part of the URI which comes
-   after the base URL) and decomposing it into parameters to determine which
-   module, controller, and action of that controller should receive the
-   request. This values of the module, controller, action and other parameters
-   are packaged into a <classname>Yaf_Request_Abstract</classname> object which is then
-   processed by <classname>Yaf_Dispatcher</classname>. Routing occurs only once:
-   when the request is initially received and before the first controller is
-   dispatched.
+   after the base URI: see <methodname>Yaf_Request_Abstract::setBaseUri</methodname>)
+   and decomposing it into parameters to determine which module, controller, and
+   action of that controller should receive the request. This values of the module,
+   controller, action and other parameters are packaged into a
+   <classname>Yaf_Request_Abstract</classname> object which is then processed by
+   <classname>Yaf_Dispatcher</classname>. Routing occurs only once: when the request
+   is initially received and before the first controller is dispatched.
 
    <classname>Yaf_Router</classname> is designed to allow for mod_rewrite-like
    functionality using pure PHP structures. It is very loosely based on Ruby
@@ -88,12 +88,12 @@ server {
   <section xml:id="yaf-router.default">
    <title>Default route</title>
    <para>
-   Yaf_Router comes preconfigured with a default route, which
-   will match URIs in the shape of controller/action. Additionally, a module
-   name may be specified as the first path element, allowing URIs of the form
-   module/controller/action. Finally, it will also match any additional
-   parameters appended to the URI by default -
-   controller/action/var1/value1/var2/value2.
+    <classname>Yaf_Router</classname> comes preconfigured with a default route
+    <classname>Yaf_Route_Static</classname>, which will match URIs in the shape of 
+    controller/action. Additionally, a module name may be specified as the first
+    path element, allowing URIs of the form module/controller/action. Finally, 
+    it will also match any additional parameters appended to the URI by default 
+    - controller/action/var1/value1/var2/value2.
     <note>
      <para>
       Module name must be defined in config, considering application.module="Index,Foo,Bar",
@@ -106,8 +106,7 @@ server {
    <para>
    Some examples of how such routes are matched:
    <example>
-    <title><classname>Yaf_Route_Static</classname>(default
-     route)example</title>
+    <title><classname>Yaf_Route_Static</classname>(default route)example</title>
    <programlisting role="conf">
 <![CDATA[
 // Assuming the following configure:
@@ -192,13 +191,21 @@ http://example/blog/archive/list/sort/alpha/date/desc
     <varlistentry xml:id="yaf-router.props.routes">
      <term><varname>_routes</varname></term>
      <listitem>
-      <para></para>
+      <para>
+      registered routes stack
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="yaf-router.props.current">
      <term><varname>_current</varname></term>
      <listitem>
-      <para></para>
+      <para>
+       after routing phase, this indicated the name of which route
+       is used to route current request.
+
+       you can get this name by
+       <methodname>Yaf_Router::getCurrentRoute</methodname>.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>

reference/yaf/yaf_request_abstract/setbaseuri.xml

@@ -4,21 +4,29 @@
 <refentry xml:id="yaf-request-abstract.setbaseuri" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Yaf_Request_Abstract::setBaseUri</refname>
-  <refpurpose>The setBaseUri purpose</refpurpose>
+  <refpurpose>set base URI</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Yaf_Request_Abstract::setBaseUri</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Yaf_Request_Abstract::setBaseUri</methodname>
    <methodparam><type>string</type><parameter>uir</parameter></methodparam>
   </methodsynopsis>
   <para>
+   Set base URI, base URI is used when doing routing, in routing phase request
+   URI is used to route a request,  while base URI is used to skip the
+   leadding part(base URI) of request URI.
 
+   That is, if comes a request with request URI a/b/c, then if you set base
+   URI to "a/b", only "/c" will be used in routing phase.
+   <note>
+    <para>
+     generally, you don't need to set this, Yaf will determine it automatically.
+    </para>
+   </note>
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,7 +36,7 @@
     <term><parameter>uir</parameter></term>
     <listitem>
      <para>
-      
+       base URI
      </para>
     </listitem>
    </varlistentry>
@@ -38,7 +46,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   bool
   </para>
  </refsect1>