From 713e033f90eb39aad8ac48916985396ca5282815 Mon Sep 17 00:00:00 2001
From: Yiyu He <dead-horse@users.noreply.github.com>
Date: Sat, 20 May 2017 10:31:02 +0800
Subject: [PATCH] docs: app.controller.foo instead of 'foo' (#942)

---
 docs/source/en/basics/router.md        | 44 +++++++++++----------
 docs/source/en/intro/quickstart.md     |  6 +--
 docs/source/zh-cn/basics/controller.md |  6 +--
 docs/source/zh-cn/basics/router.md     | 55 +++++++++++++-------------
 docs/source/zh-cn/intro/quickstart.md  |  6 +--
 5 files changed, 60 insertions(+), 57 deletions(-)

diff --git a/docs/source/en/basics/router.md b/docs/source/en/basics/router.md
index da9e30e415..f526c02a33 100644
--- a/docs/source/en/basics/router.md
+++ b/docs/source/en/basics/router.md
@@ -12,7 +12,7 @@ By unifying routing rules, routing logics are free from scatter that may cause u
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/user/:id', 'user.info');
+  app.get('/user/:id', app.controller.user.info);
 };
 ```
 
@@ -53,7 +53,9 @@ The complete definition of router includes 5 major parts:
 - router-name defines a alias for the route, and URL can be generated by helper method `pathFor` and `urlFor` provided by Helper. (Optional)
 - path-match - URL path of the route.
 - middleware1 - multiple Middleware can be configured in Router. (Optional)
-- controller.action - it's a string, take care. The framework will find the Controller sharing the name under `app/controller`, then assign the process to the configured action method. The action can be omitted if the Controller exports a method directly.
+- controller - specific the controller of this router, this param can be tow types:
+  * `app.controller.user.fetch` - directly point to a controller
+  * `'user.fetch'` - simplified as a string,
 
 ### Notices
 
@@ -65,11 +67,11 @@ The complete definition of router includes 5 major parts:
 Here are some examples of writing routing rules:
 
 ```js
-app.get('/home', 'home');
-app.get('/user/:id', 'user.page');
-app.post('/admin', isAdmin, 'admin');
-app.post('user', '/user', isLoginUser, hasAdminPermission, 'user.create');
-app.post('/api/v1/comments', 'v1.comments.create'); // app/controller/v1/comments.js
+app.get('/home', app.controller.home);
+app.get('/user/:id', app.controller.user.page);
+app.post('/admin', isAdmin, app.controller.admin);
+app.post('user', '/user', isLoginUser, hasAdminPermission, app.controller.user.create);
+app.post('/api/v1/comments', app.controller.v1.comments.create); // app/controller/v1/comments.js
 ```
 
 ### RESTful style URL definition
@@ -79,8 +81,8 @@ We provide `app.resources('router-name', 'path-match', 'controller-name')` to ge
 ```js
 // app/router.js
 module.exports = app => {
-  app.resources('posts', '/posts', 'posts');
-  app.resources('users', '/api/v1/users', 'v1.users'); // app/controller/v1/users.js
+  app.resources('posts', '/posts', app.controller.posts);
+  app.resources('users', '/api/v1/users', app.controller.v1.users); // app/controller/v1/users.js
 };
 ```
 
@@ -126,7 +128,7 @@ More practical examples will be shown below to demonstrate how to use the router
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/search', 'search');
+  app.get('/search', app.controller.search);
 };
 
 // app/controller/search.js
@@ -142,7 +144,7 @@ module.exports = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/user/:id/:name', 'user.info');
+  app.get('/user/:id/:name', app.controller.user.info);
 };
 
 // app/controller/user.js
@@ -160,7 +162,7 @@ Regular expressions, as well, can be used in routing rules to aquire parameters
 ```js
 // app/router.js
 module.exports = app => {
-  app.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, 'package.detail');
+  app.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, app.controller.package.detail);
 };
 
 // app/controller/package.js
@@ -178,7 +180,7 @@ exports.detail = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('/form', 'form');
+  app.post('/form', app.controller.form);
 };
 
 // app/controller/form.js
@@ -212,7 +214,7 @@ exports.security = {
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('/user', 'user');
+  app.post('/user', app.controller.user);
 };
 
 // app/controller/user.js
@@ -242,7 +244,7 @@ exports.create = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('index', '/home/index', 'home.index');
+  app.get('index', '/home/index', app.controller.home.index);
   app.redirect('/', '/home/index', 302);
 };
 
@@ -259,7 +261,7 @@ exports.index = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/search', 'search');
+  app.get('/search', app.controller.search);
 };
 
 // app/controller/search.js
@@ -299,7 +301,7 @@ module.exports = () => {
 
 // app/router.js
 module.exports = app => {
-  app.get('s', '/search', app.middlewares.uppercase(), 'search')
+  app.get('s', '/search', app.middlewares.uppercase(), app.controller.search)
 };
 
 // curl http://localhost:7001/search2?name=egg
@@ -320,13 +322,13 @@ module.exports = app => {
 
 // app/router/news.js
 module.exports = app => {
-  app.get('/news/list', 'news.list');
-  app.get('/news/detail', 'news.detail');
+  app.get('/news/list', app.controller.news.list);
+  app.get('/news/detail', app.controller.news.detail);
 };
 
 // app/router/admin.js
 module.exports = app => {
-  app.get('/admin/user', 'admin.user');
-  app.get('/admin/log', 'admin.log');
+  app.get('/admin/user', app.controller.admin.user);
+  app.get('/admin/log', app.controller.admin.log);
 };
 ```
diff --git a/docs/source/en/intro/quickstart.md b/docs/source/en/intro/quickstart.md
index a01dd4d16e..c8e166cd0b 100644
--- a/docs/source/en/intro/quickstart.md
+++ b/docs/source/en/intro/quickstart.md
@@ -86,7 +86,7 @@ Then edit the router file and add a mapping.
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/', 'home.index');
+  app.get('/', app.controller.home.index);
 };
 ```
 
@@ -228,8 +228,8 @@ module.exports = app => {
 
 // app/router.js
 module.exports = app => {
-  app.get('/', 'home.index');
-  app.get('/news', 'news.list');
+  app.get('/', app.controller.home.index);
+  app.get('/news', app.controller.news.list);
 };
 ```
 
diff --git a/docs/source/zh-cn/basics/controller.md b/docs/source/zh-cn/basics/controller.md
index 07ebc07c88..f10848525f 100644
--- a/docs/source/zh-cn/basics/controller.md
+++ b/docs/source/zh-cn/basics/controller.md
@@ -53,12 +53,12 @@ module.exports = app => {
 }
 ```
 
-我们通过上面的代码定义了一个 `PostController` 的类，类里面的每一个方法都可以作为一个 Controller 在 Router 中引用到。
+我们通过上面的代码定义了一个 `PostController` 的类，类里面的每一个方法都可以作为一个 Controller 在 Router 中引用到，我们可以从 `app.controller` 根据文件名和方法名定位到它。
 
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('createPost', '/api/posts', 'post.create');
+  app.post('createPost', '/api/posts', app.controller.post.create);
 }
 ```
 
@@ -67,7 +67,7 @@ Controller 支持多级目录，例如如果我们将上面的 Controller 代码
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('createPost', '/api/posts', 'sub.post.create');
+  app.post('createPost', '/api/posts', app.controller.sub.post.create);
 }
 ```
 
diff --git a/docs/source/zh-cn/basics/router.md b/docs/source/zh-cn/basics/router.md
index 594b577307..6c71f84de4 100644
--- a/docs/source/zh-cn/basics/router.md
+++ b/docs/source/zh-cn/basics/router.md
@@ -13,7 +13,7 @@ Router 主要用来描述请求 URL 和具体承担执行动作的 Controller 
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/user/:id', 'user.info');
+  app.get('/user/:id', app.controller.user.info);
 };
 ```
 
@@ -35,10 +35,10 @@ exports.info = function* (ctx) {
 下面是路由的完整定义，参数可以根据场景的不同，自由选择：
 
 ```js
-app.verb('path-match', 'controller.action');
-app.verb('router-name', 'path-match', 'controller.action');
-app.verb('path-match', middleware1, ..., middlewareN, 'controller.action');
-app.verb('router-name', 'path-match', middleware1, ..., middlewareN, 'controller.action');
+app.verb('path-match', app.controller.controller.action);
+app.verb('router-name', 'path-match', app.controller.controller.action);
+app.verb('path-match', middleware1, ..., middlewareN, app.controller.controller.action);
+app.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.controller.action);
 ```
 
 路由完整定义主要包括5个主要部分:
@@ -56,8 +56,9 @@ app.verb('router-name', 'path-match', middleware1, ..., middlewareN, 'controller
 - router-name 给路由设定一个别名，可以通过 Helper 提供的辅助函数 `pathFor` 和 `urlFor` 来生成 URL。(可选)
 - path-match - 路由 URL 路径。
 - middleware1 - 在 Router 里面可以配置多个 Middleware。(可选)
-- controller.action - 注意是字符串，框架会自动从 `app/controller` 目录中去查找同名 Controller，
-并且把处理指定到配置的 action 方法。如果 Controller 文件直接 export 一个方法，可以省略 action。
+- controller - 指定路由映射到的具体的 controller 上，controller 可以有两种写法：
+  * `app.controller.user.fetch` - 直接指定一个具体的 controller
+  * `'user.fetch'` - 可以简写为字符串形式
 
 ### 注意事项
 
@@ -69,23 +70,23 @@ app.verb('router-name', 'path-match', middleware1, ..., middlewareN, 'controller
 下面是一些路由定义的方式：
 
 ```js
-app.get('/home', 'home');
-app.get('/user/:id', 'user.page');
-app.post('/admin', isAdmin, 'admin');
-app.post('/user', isLoginUser, hasAdminPermission, 'user.create');
-app.post('/api/v1/comments', 'v1.comments.create'); // app/controller/v1/comments.js
+app.get('/home', app.controller.home);
+app.get('/user/:id', app.controller.user.page);
+app.post('/admin', isAdmin, app.controller.admin);
+app.post('/user', isLoginUser, hasAdminPermission, app.controller.user.create);
+app.post('/api/v1/comments', app.controller.v1.comments.create); // app/controller/v1/comments.js
 ```
 
 ### RESTful 风格的 URL 定义
 
 如果想通过 RESTful 的方式来定义路由，
-我们提供了 `app.resources('routerName', 'pathMatch', 'controllerName')` 快速在一个路径上生成 [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 路由结构。
+我们提供了 `app.resources('routerName', 'pathMatch', controller)` 快速在一个路径上生成 [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 路由结构。
 
 ```js
 // app/router.js
 module.exports = app => {
-  app.resources('posts', '/api/posts', 'posts');
-  app.resources('users', '/api/v1/users', 'v1.users'); // app/controller/v1/users.js
+  app.resources('posts', '/api/posts', app.controller.posts);
+  app.resources('users', '/api/v1/users', app.controller.v1.users); // app/controller/v1/users.js
 };
 ```
 
@@ -132,7 +133,7 @@ exports.destroy = function* () {};
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/search', 'search');
+  app.get('/search', app.controller.search);
 };
 
 // app/controller/search.js
@@ -148,7 +149,7 @@ module.exports = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/user/:id/:name', 'user.info');
+  app.get('/user/:id/:name', app.controller.user.info);
 };
 
 // app/controller/user.js
@@ -166,7 +167,7 @@ exports.info = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, 'package.detail');
+  app.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, app.controller.package.detail);
 };
 
 // app/controller/package.js
@@ -184,7 +185,7 @@ exports.detail = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('/form', 'form');
+  app.post('/form', app.controller.form);
 };
 
 // app/controller/form.js
@@ -218,7 +219,7 @@ exports.security = {
 ```js
 // app/router.js
 module.exports = app => {
-  app.post('/user', 'user');
+  app.post('/user', app.controller.user);
 };
 
 // app/controller/user.js
@@ -248,7 +249,7 @@ exports.create = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('index', '/home/index', 'home.index');
+  app.get('index', '/home/index', app.controller.home.index);
   app.redirect('/', '/home/index', 302);
 };
 
@@ -265,7 +266,7 @@ exports.index = function* (ctx) {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/search', 'search');
+  app.get('/search', app.controller.search);
 };
 
 // app/controller/search.js
@@ -305,7 +306,7 @@ module.exports = () => {
 
 // app/router.js
 module.exports = app => {
-  app.get('s', '/search', app.middlewares.uppercase(), 'search')
+  app.get('s', '/search', app.middlewares.uppercase(), app.controller.search)
 };
 
 // curl http://localhost:7001/search2?name=egg
@@ -326,13 +327,13 @@ module.exports = app => {
 
 // app/router/news.js
 module.exports = app => {
-  app.get('/news/list', 'news.list');
-  app.get('/news/detail', 'news.detail');
+  app.get('/news/list', app.controller.news.list);
+  app.get('/news/detail', app.controller.news.detail);
 };
 
 // app/router/admin.js
 module.exports = app => {
-  app.get('/admin/user', 'admin.user');
-  app.get('/admin/log', 'admin.log');
+  app.get('/admin/user', app.controller.admin.user);
+  app.get('/admin/log', app.controller.admin.log);
 };
 ```
diff --git a/docs/source/zh-cn/intro/quickstart.md b/docs/source/zh-cn/intro/quickstart.md
index 6a35e30f1a..985c0ef138 100644
--- a/docs/source/zh-cn/intro/quickstart.md
+++ b/docs/source/zh-cn/intro/quickstart.md
@@ -78,7 +78,7 @@ module.exports = app => {
 ```js
 // app/router.js
 module.exports = app => {
-  app.get('/', 'home.index');
+  app.get('/', app.controller.home.index);
 };
 ```
 
@@ -212,8 +212,8 @@ module.exports = app => {
 
 // app/router.js
 module.exports = app => {
-  app.get('/', 'home.index');
-  app.get('/news', 'news.list');
+  app.get('/', app.controller.home.index);
+  app.get('/news', app.controller.news.list);
 };
 ```