Update 接口文档与代码对比工具说明.md

接口文档和代码对比工具/接口文档与代码对比工具说明.md

-## 1 工具需要做的配置及使用
+## 1 工具需要做的配置及使用
 ## 1 工具需要做的配置及使用
 工具以python脚本形式存在，在Ubuntu Linux上执行。
 预备条件：
-1.安装了go，版本go 1.12及以上。
-2.下载了plugin代码，并可以编译
-3.假定plugin代码路径为/home/user/code/go/plugin
+1.安装了go，版本go 1.12及以上。  
+2.下载了plugin代码，并可以编译  
+3.假定plugin代码路径为/home/user/code/go/plugin  
 
 配置步骤：
-1.文件interface_check_tool.py中配置如下路径
-plugpath='/home/user/code/go/plugin/plugin'
-2.文件interface_check_tool.py中配置要核对的接口文档编号
-cids = ['93', '94', '100','99','98','97','96','102','105','104','108','110','115','118','134','135']
-这里的cid对应于url：https://chain.33.cn/document/93 中的最后一个编号，可以从https://chain.33.cn/网站上查看具体的接口文档的url。
-![接口文档编号](./image/cid.png)
-将所有需要核对接口的url中cid信息都添加到cids列表变量中。
-3.执行脚本python interface_check_tool.py
-脚本将通过类似https://mapi.bityuan.com/v1/article/helps?cid=93的方式，访问配置的所有接口文档。
-脚本将根据文档中的接口名称及路径信息，通过go doc命令从本地编译环境中的chain33工程代码或者plugin工程代码中得到对应消息接口的代码定义。
-脚本将上述两者中的相同接口的字段及类型信息进行比较，并记录结果。
-4.最终的汇总结果输出在脚本interface_check_tool.py的所在目录下的result文件中。
+1.文件interface_check_tool.py中配置如下路径  
+plugpath='/home/user/code/go/plugin/plugin'  
+2.文件interface_check_tool.py中配置要核对的接口文档编号  
+cids = ['93', '94', '100','99','98','97','96','102','105','104','108','110','115','118','134','135']  
+这里的cid对应于url：https://chain.33.cn/document/93 中的最后一个编号，可以从https://chain.33.cn/网站上查看具体的接口文档的url。  
+![接口文档编号](./image/cid.png)  
+将所有需要核对接口的url中cid信息都添加到cids列表变量中。  
+3.执行脚本python interface_check_tool.py  
+脚本将通过类似https://mapi.bityuan.com/v1/article/helps?cid=93的方式，访问配置的所有接口文档。  
+脚本将根据文档中的接口名称及路径信息，通过go doc命令从本地编译环境中的chain33工程代码或者plugin工程代码中得到对应消息接口的代码定义。  
+脚本将上述两者中的相同接口的字段及类型信息进行比较，并记录结果。  
+4.最终的汇总结果输出在脚本interface_check_tool.py的所在目录下的result文件中。  
 ```json
 {
 	"result":[
@@ -125,13 +125,13 @@ cids = ['93', '94', '100','99','98','97','96','102','105','104','108','110','115
 	}	]
 }
 ```
-结果信息中，注明了某一个接口文档中所有接口用到的接口消息定义与代码中的对比结果，如果某个接口消息对比结果不一致（文档和代码存在差异），会有具体的差异信息。
+结果信息中，注明了某一个接口文档中所有接口用到的接口消息定义与代码中的对比结果，如果某个接口消息对比结果不一致（文档和代码存在差异），会有具体的差异信息。  
 
 
-## 2 工具工作原理及文档格式要求
-文档格式需要符合约定要求，工具才能识别并进行自动化对比。
+## 2 工具工作原理及文档格式要求  
+文档格式需要符合约定要求，工具才能识别并进行自动化对比。  
 ![交易接口的文档格式](./image/tx_doc.png)
-以交易接口为例，格式特点如下：
+以交易接口为例，格式特点如下：  
 ```json
 **请求报文[rpc/types/CreateTx]：**
 json
@@ -168,21 +168,21 @@ json
 |execer|string|-|执行器名称，如果是构造平行链的基础代币，此处要填写user.p.xxx.coins
 ```
 
-(1)“请求报文[rpc/types/CreateTx]”关键字说明了这是一个请求接口，消息参数参见 chain33/rpc/types包里的CreateTx定义。
-(2)"method":"Chain33.CreateRawTransaction" 说明了具体的接口名称CreateRawTransaction。
-(3)"参数说明"，是文档中描述的CreateTx消息的字段定义。工具根据“----|----|----”特征认为是文档对字段说明的开始，并扫描连续的多个字段名及类型，直到遇到空行结束。
+(1)“请求报文[rpc/types/CreateTx]”关键字说明了这是一个请求接口，消息参数参见 chain33/rpc/types包里的CreateTx定义。  
+(2)"method":"Chain33.CreateRawTransaction" 说明了具体的接口名称CreateRawTransaction。  
+(3)"参数说明"，是文档中描述的CreateTx消息的字段定义。工具根据“----|----|----”特征认为是文档对字段说明的开始，并扫描连续的多个字段名及类型，直到遇到空行结束。  
 
-检测脚本要完成的事情就是：
-（1）在chain33代码路径中，通过go doc rpc/types CreateTx得到代码中的CreateTx的字段定义。
-（2）从文档中解析出CreateTx的字段说明。
-（3）将两者对比，确认是否一致，如果不一致，记录差异。
+检测脚本要完成的事情就是：  
+（1）在chain33代码路径中，通过go doc rpc/types CreateTx得到代码中的CreateTx的字段定义。  
+（2）从文档中解析出CreateTx的字段说明。  
+（3）将两者对比，确认是否一致，如果不一致，记录差异。  
 
-程序的处理流程：
+程序的处理流程：  
 
 
 ## 3 文档格式样例
 
-1.接口消息为chain33中的rpc/types 或者 types 包中的消息
+1.接口消息为chain33中的rpc/types 或者 types 包中的消息  
 ```json
 #### 1.1.2 交易签名 SignRawTx
 
@@ -236,11 +236,11 @@ json
 |result|string|交易签名后的十六进制字符串|
 ```
 
-从chain33的工程代码中，找到接口定义：
-func (c *Chain33) SignRawTx(in *types.ReqSignRawTx, result *interface{}) error 
-其中，请求参数ReqSignRawTx定义在types包中，所以，如下关键字指明包路径：
-**请求报文[types/ReqSignRawTx]：**
-响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[types/ReqSignRawTx]”的信息）。
+从chain33的工程代码中，找到接口定义：  
+func (c *Chain33) SignRawTx(in *types.ReqSignRawTx, result *interface{}) error   
+其中，请求参数ReqSignRawTx定义在types包中，所以，如下关键字指明包路径：  
+**请求报文[types/ReqSignRawTx]：**  
+响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[types/ReqSignRawTx]”的信息）。  
 
 2.接口消息为plugin中的具体的包中的消息
 ```json
@@ -297,12 +297,12 @@ Response:
 ` ` `
 ```
 
-从plugin的工程代码中，找到接口定义：
-func (c *Jrpc) CreateRawTokenRevokeTx(param *tokenty.TokenRevokeCreate, result *interface{}) error
-其中，请求参数TokenRevokeCreate定义在dapp/token/types包中，所以，如下关键字指明其包路径：
-**请求报文[dapp/token/types/TokenRevokeCreate]：**
+从plugin的工程代码中，找到接口定义：  
+func (c *Jrpc) CreateRawTokenRevokeTx(param *tokenty.TokenRevokeCreate, result *interface{}) error  
+其中，请求参数TokenRevokeCreate定义在dapp/token/types包中，所以，如下关键字指明其包路径：  
+**请求报文[dapp/token/types/TokenRevokeCreate]：**  
 
-响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[dapp/token/types/TokenRevokeCreate]”的信息）。
+响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[dapp/token/types/TokenRevokeCreate]”的信息）。  
 
 3.接口消息为chain33中某个dapp的具体的包中的消息，Chain33.CreateTransaction接口中承载具体执行器的action信息
 ```json
@@ -355,10 +355,10 @@ payload携带的内容格式如下：
 |----|----|----|
 |result|string|交易的hex字节码|
 ```
-从chain33的工程代码中，找到具体的ModifyConfig消息定义,
-请求参数ModifyConfig定义在types包中，所以，如下关键字指明其包路径：
-**请求报文[types/ModifyConfig]：**
-响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[types/ModifyConfig]”的信息）。
+从chain33的工程代码中，找到具体的ModifyConfig消息定义,  
+请求参数ModifyConfig定义在types包中，所以，如下关键字指明其包路径：  
+**请求报文[types/ModifyConfig]：**  
+响应消息是简单的string类型，可以不用检测（不需要在关键字“响应报文”后增加类似“[types/ModifyConfig]”的信息）。  
 
 4.接口消息为plugin中某个dapp的具体的包中的消息，Chain33.Query接口中承载具体执行器的funcName信息
 
@@ -419,15 +419,15 @@ payload携带的内容格式如下：
 |----|----|----|
 |eventID|[]string|符合条件的事件ID数组|
 ```
-从plugin的工程代码中，找到具体dapp/oracle中的QueryEventID消息定义,
-请求参数QueryEventID定义在dapp/oracle/types/包中，所以，如下关键字指明其包路径：
-**请求报文[dapp/oracle/types/QueryEventID]**
-响应消息是简单的ReplyEventIDs结构类型，该类型定义在dapp/oracle/types/包中，所以，如下关键字知名其包路径：
-**响应报文[dapp/oracle/types/ReplyEventIDs]**
+从plugin的工程代码中，找到具体dapp/oracle中的QueryEventID消息定义,  
+请求参数QueryEventID定义在dapp/oracle/types/包中，所以，如下关键字指明其包路径：  
+**请求报文[dapp/oracle/types/QueryEventID]**  
+响应消息是简单的ReplyEventIDs结构类型，该类型定义在dapp/oracle/types/包中，所以，如下关键字知名其包路径：  
+**响应报文[dapp/oracle/types/ReplyEventIDs]**  
 
 ## 4 重点强调
 
-1.目前各个接口的请求消息已经做过统一修订，修改了很多字段缺失、类型描述错误、字段名称错误等问题，后续有新的接口或者接口变化时，请遵循上述要求，确保文档格式符合要求，这样检测工具可以正常工作。
+1.目前各个接口的请求消息已经做过统一修订，修改了很多字段缺失、类型描述错误、字段名称错误等问题，后续有新的接口或者接口变化时，请遵循上述要求，确保文档格式符合要求，这样检测工具可以正常工作。  
 ```json
 **请求报文[types/ModifyConfig]：**               //严格按这个格式，[]中的内容按消息的实际所在包名及消息名进行拼接填写。
 ` ` `json
@@ -447,10 +447,10 @@ payload携带的内容格式如下：
                                                   //字段说明完毕，空一个空行，说明字段结束，检测工具据此判断停止解析字段。
 ```
 
-对于接口由Chain33.CreateTransaction承载时，参见 3.3中的说明。
-对于接口由Chain33.Query承载时，参见3.4中的说明。
+对于接口由Chain33.CreateTransaction承载时，参见 3.3中的说明。  
+对于接口由Chain33.Query承载时，参见3.4中的说明。  
 
-2.对于各个接口的响应消息，还存在较多的问题，需要每个负责人按要求整改响应消息的描述，使之格式一致，符合统一标准，使检测工具可以检测响应消息。
+2.对于各个接口的响应消息，还存在较多的问题，需要每个负责人按要求整改响应消息的描述，使之格式一致，符合统一标准，使检测工具可以检测响应消息。  
 ```json
 **响应报文[dapp/oracle/types/ReplyEventIDs]**     //严格按照这个格式，[]中的内容按消息的实际所在包名及消息名进行拼接填写。 如果result为string类型，则不携带[]部分，不做检测。
 ` ` `json