From d35e43f90ee1ef741ad14f5a69f9781a8b6780d2 Mon Sep 17 00:00:00 2001
From: SkyAo <csvwolf@qq.com>
Date: Tue, 16 Aug 2016 17:19:34 +0800
Subject: [PATCH] add alert & button docs and fix alert close event

---
 examples/docs/alert.md      | 54 ++++++++++++++++++++++++++++++-------
 examples/docs/button.md     | 49 +++++++++++++++++++++++++++------
 packages/alert/src/main.vue |  2 +-
 3 files changed, 87 insertions(+), 18 deletions(-)

diff --git a/examples/docs/alert.md b/examples/docs/alert.md
index 5304eaf13..b6ce5b321 100644
--- a/examples/docs/alert.md
+++ b/examples/docs/alert.md
@@ -1,3 +1,12 @@
+<script>
+  export default {
+    methods: {
+      hello() {
+        alert('Hello World!');
+      }
+    }
+  }
+</script>
 <style>
   .demo-box.demo-alert .el-alert {
     margin: 20px 0 0;
@@ -6,6 +15,8 @@
 
 ## 基本用法
 
+alert组件提供四种主题，由`type`属性指定，默认值为`info`，下面的示例展示了四种不同的主题。
+
 <div class="demo-box demo-alert">
   <el-alert title="成功提示的文案" type="success"></el-alert>
   <el-alert title="消息提示的文案" type="info"></el-alert>
@@ -22,16 +33,32 @@
 
 ## 自定义关闭按钮
 
+在alert组件中，你可以设置是否可关闭，关闭按钮的文本以及关闭时的回调函数。
+
+`closable`属性决定是否可关闭，接受`boolean`，默认为`true`。
+
+你可以设置`close-text`属性来代替右侧的关闭图标，注意：`close-text`必须为文本。
+
+设置`close`事件来设置关闭时的回调。
+
+下面的示例展示了上述三种情况：
+
 <div class="demo-box demo-alert">
-  <el-alert title="成功提示的文案" type="success" close-text="知道了"></el-alert>
+  <el-alert title="不可关闭的alert" type="success" :closable="false"></el-alert>
+  <el-alert title="自定义close-text" type="info" close-text="知道了"></el-alert>
+  <el-alert title="设置了回调的alert" type="warning" @close="hello"></el-alert>
 </div>
 
 ```html
-<el-alert title="成功提示的文案" type="success" close-text="知道了"></el-alert>
+<el-alert title="不可关闭" type="success" :closable="false"></el-alert>
+<el-alert title="自定义close-text" type="info" close-text="知道了"></el-alert>
+<el-alert title="设置了回调的alert" type="warning" @close="hello"></el-alert>
 ```
 
 ## 带有 icon
 
+通过设置`show-icon`属性来显示alert的icon，这能更有效的向用户展示你的显示意图。
+
 <div class="demo-box demo-alert">
   <el-alert title="成功提示的文案" type="success" show-icon></el-alert>
   <el-alert title="消息提示的文案" type="info" show-icon></el-alert>
@@ -48,20 +75,24 @@
 
 ## 带有辅助性文字介绍
 
+除了必填的`title`属性外，你可以设置`description`属性来帮助你更好的介绍，我们称之为辅助性文字。辅助性文字只能存放单行文本，会自动换行显示。
+
 <div class="demo-box demo-alert">
-  <el-alert title="成功提示的文案" type="success" description="文字说明文字说明文字说明文字说明文字说明文字说明"></el-alert>
+  <el-alert title="带辅助性文字介绍" type="success" description="这是一句绕口令：黑灰化肥会挥发发灰黑化肥挥发；灰黑化肥会挥发发黑灰化肥发挥。 黑灰化肥会挥发发灰黑化肥黑灰挥发化为灰……"></el-alert>
 </div>
 
 ```html
 <el-alert
-  title="成功提示的文案"
+  title="带辅助性文字介绍"
   type="success"
-  description="文字说明文字说明文字说明文字说明文字说明文字说明">
+  description="这是一句绕口令：黑灰化肥会挥发发灰黑化肥挥发；灰黑化肥会挥发发黑灰化肥发挥。 黑灰化肥会挥发发灰黑化肥黑灰挥发化为灰……">
 </el-alert>
 ```
 
 ## 带有 icon 和辅助性文字介绍
 
+最后，这是一个同时具有icon和辅助性文字的样例。
+
 <div class="demo-box demo-alert">
   <el-alert title="成功提示的文案" type="success" description="文字说明文字说明文字说明文字说明文字说明文字说明" show-icon></el-alert>
   <el-alert title="消息提示的文案" type="info" description="文字说明文字说明文字说明文字说明文字说明文字说明" show-icon></el-alert>
@@ -99,13 +130,18 @@
 </el-alert>
 ```
 
-## API
+## Attributes
 | 参数      | 说明          | 类型      | 可选值                           | 默认值  |
 |---------- |-------------- |---------- |--------------------------------  |-------- |
-| title | 标题, 必选参数 | string | | |
+| **title** | 标题，**必选参数** | string | | |
 | type | 主题 | string | 'success', 'warning', 'info', 'error' | 'info' |
-| description | 说明文字 | string | | |
+| description | 辅助性文字 | string | | |
 | closable | 是否可关闭 | boolean | | true |
 | closeText | 关闭按钮自定义文本 | string | | |
 | showIcon | 是否显示图标 | boolean | | false |
-| onClose | 关闭时的回调函数 | function | | |
+
+
+## Events
+| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+|---------- |-------------- |---------- |--------------------------------  |-------- |
+| close | 关闭时的回调函数 | function | | |
diff --git a/examples/docs/button.md b/examples/docs/button.md
index 3e806c636..18f45c342 100644
--- a/examples/docs/button.md
+++ b/examples/docs/button.md
@@ -31,6 +31,8 @@
 
 ## 基础用法
 
+button组件默认提供7种主题，由`type`属性来定义，默认为`default`：
+
 <div class="demo-box demo-button">
   <el-button>Default</el-button>
   <el-button type="primary">primary</el-button>
@@ -38,10 +40,18 @@
   <el-button type="warning">warning</el-button>
   <el-button type="danger">danger</el-button>
   <el-button type="info">info</el-button>
-  <el-button :disabled="true">disabled</el-button>
   <el-button type="text">text button</el-button>
 </div>
 
+你可以使用`disabled`属性来定义按钮是否可用，它接受一个`Boolean`值：
+
+<div class="demo-box demo-button">
+  <el-button>Default</el-button>
+  <el-button :disabled="true">disabled</el-button>
+</div>
+
+下面是他们的样例代码：
+
 ```html
 <el-button>Default</el-button>
 <el-button type="primary">primary</el-button>
@@ -49,12 +59,20 @@
 <el-button type="warning">warning</el-button>
 <el-button type="danger">danger</el-button>
 <el-button type="info">info</el-button>
-<el-button :disabled="true">disabled</el-button>
 <el-button type="text">text button</el-button>
+<el-button :disabled="true">disabled</el-button>
 ```
 
 ## Plain Button
 
+默认的`Default`主题，我们称之为朴素按钮(Plain Button)，朴素按钮同样设置了不同的`type`属性对应的样式（可选值同上），默认为`info`。
+
+设置`plain`属性，它接受一个`Boolean`。
+
+注意，在该情况下，`type`虽然可以为`text`，但是是没有意义的，会显示为`text button`的样式。
+
+你可以Hover在样例上进行预览：
+
 <div class="demo-box demo-button">
   <el-button :plain="true">Default</el-button>
   <el-button :plain="true" type="success">success</el-button>
@@ -73,6 +91,8 @@
 
 ## 尺寸
 
+button组件提供除了默认值以外的三种尺寸：`large`、`small`、`mini`来满足不同的需求，通过设置`size`属性来配置它们。
+
 <div class="demo-box demo-button">
   <el-button type="primary" size="large">large</el-button>
   <el-button type="primary">Default</el-button>
@@ -89,27 +109,38 @@
 
 ## Loading
 
+button组件提供的`loading`属性可以方便的让你处理 loading 状态，它接受一个`Boolean`，要设置为 loading 状态，只要设置`loading`属性为`true`即可，下面是一个样例：
+
 <div class="demo-box demo-button">
   <el-button type="primary" :loading="true">Button</el-button>
 </div>
-<p>点击后变成 loading 状态</p>
+
+点击后变成 loading 状态的样例，尝试点击它：
+
 <div class="demo-box demo-button">
-  <el-button type="primary" :loading="isLoading" @click="isLoading = true">Button</el-button>
-  <el-button type="primary" icon="search" :loading="isLoading2" @click="isLoading2 = true">Button</el-button>
+  <el-button type="primary" :loading="isLoading" @click.native="isLoading = true">Button</el-button>
+  <el-button type="primary" icon="search" :loading="isLoading2" @click.native="isLoading2 = true">Button</el-button>
 </div>
 
 ```html
 <el-button type="primary" :loading="true">Button</el-button>
 
-<el-button type="primary" :loading="isLoading" @click="isLoading = true">Button</el-button>
-<el-button type="primary" icon="search" :loading="isLoading2" @click="isLoading2 = true">Button</el-button>
+<el-button type="primary" :loading="isLoading" @click.native="isLoading = true">Button</el-button>
+<el-button type="primary" icon="search" :loading="isLoading2" @click.native="isLoading2 = true">Button</el-button>
 ```
 
 ## 图标按钮
 
+理所当然的，Element也支持图标按钮，设置`icon`属性即可，icon的列表可以参考Element的icon组件，下面是简单的预览：
+
 <div class="demo-box demo-button">
   <el-button type="primary" icon="edit"></el-button>
   <el-button type="primary" icon="search">Search</el-button>
+</div>
+
+除此以外，你也可以设置在文字右边的icon，只要使用`i`标签即可，使用图标组件来实现它：
+
+<div class="demo-box demo-button">
   <el-button type="primary">Upload<i class="el-icon-upload el-icon-right"></i></el-button>
 </div>
 
@@ -121,6 +152,8 @@
 
 ## 按钮组
 
+如果你需要多个并列的按钮，按钮组可以帮你轻松的实现它，使用`<el-button-group>`标签来嵌套你的按钮即可。
+
 <div class="demo-box demo-button">
   <el-button-group>
     <el-button>Button</el-button>
@@ -149,7 +182,7 @@
 </el-button-group>
 ```
 
-## API
+## Attributes
 | 参数      | 说明    | 类型      | 可选值       | 默认值   |
 |---------- |-------- |---------- |-------------  |-------- |
 | size     | 尺寸   | string  |   large,small,mini            |         |
diff --git a/packages/alert/src/main.vue b/packages/alert/src/main.vue
index e8c27a76b..19558612d 100644
--- a/packages/alert/src/main.vue
+++ b/packages/alert/src/main.vue
@@ -57,7 +57,7 @@
     methods: {
       close() {
         this.visible = false;
-        this.$emit('onClose');
+        this.$emit('close');
       }
     },