例如,如果我在UsersController中有一个edit()方法,它更新User模型的指定字段,其骨架如下所示(为简洁起见,我简化了代码)：
public function edit() {
//Get arguments
$args = $this->request->data['args'];
$id = $args['id'];
//Perform processing
if (!$this->User->exists($id)) {
$data = $this->createError(300);
}
else {
$this->User->id = $id;
$saveData = array();
if (isset([$args['first_name'])) {
$saveData['User']['first_name'] = $args['first_name'];
}
if (isset([$args['last_name'])) {
$saveData['User']['last_name'] = $args['last_name'];
}
$isSaved = $this->User->save($saveData);
if (count($this->User->validationErrors) > 0) {
$data = $this->createError(202,$this->User->validationErrors);
}
else {
$data = array('status' => $isSaved ? 1 : 0);
}
}
//Output data
return $data;
}
我可能会发送一个带有以下JSON的请求来修改用户的名字和姓氏：
{
"id": 1
"first_name": "John"
"last_name": "Doe"
}
如果API调用成功,该方法将返回：
{
"status": 1
}
如果它不成功,也许由于数据验证失败,该方法可能会返回如下内容：
{
"status": 0
"code": 202,"messages": {
"first_name": {
"Numeric characters are not allowed."
}
}
}
我知道我可以使用PHPDocumentor的@return和@param分别记录返回值和参数,但是从文档中可以看出没有关于JSON返回的内容.
例如,我可以将返回类型记录为
@return $value string A JSON string that contains the status code and error messages if applicable.
但我几乎不认为这是正确的,特别是对于涉及更复杂数据结构的回报(想象类似Twitter的状态/ user_timeline),特别是对于“获取”和“视图”API方法.
另一方面,对于参数,我不确定为每个参数创建一行是否正确(考虑所有参数都包含在一个JSON字符串中),如：
@param string $id The ID of the user to be updated. @param string $first_name optional The first name of the user. @param string $last_name optional The last name of the user.
如果PHPDocumentor无法满足这种需求,我愿意探索其他选项 – 只是建议！
由于没有将明确的参数传递给edit(),所以无论如何都不应该使用@param标签.最好的情况是,可能包含一个“@uses UserController :: $request”,其描述解释了它的$data数组如何在$data的”args’]键中找到任何“edit()的参数”.解释[‘args’]及其结构所需的信息必须是纯文本描述.这里有一些“结构化文档布局”没有意义……这样的doc元素只存在于1)与其他文档链接,2)在显示元素时影响doc布局格式.我想我会在docblock for edit()中像这样接近它：
* @uses UserController::$request * $request has its own $data array,whose ['args'] key * should contain a JSON value. In the JSON,keys represent * the fields to edit,values are the new values.
至于返回,因为这里有一个实际的返回而不是仅仅进行幕后修改,我会使用一个真正的@return标签：
* @return string JSON that indicates success/failure of the update,* or JSON that indicates an error occurred.
你当然可以通过在每个点显示JSON字符串的示例来扩展它,但除了文档能够像实际的JSON而不仅仅是文本一样呈现JSON之外,我看不出你还能做什么.我可能会选择仅在docblock的Long Description中显示状态返回JSON示例,并将读者引用到createError()方法的文档以查看错误JSON布局,而不是尝试将它们全部塞入标记中.
/**
* edit() method
*
* The edit() method examines values already set elsewhere,acts on the edits requested
* by those values,and returns an indication of whether or not the edits succeeded.
*
* An array key of $data['args'] must be set in the UserController::$request object.
* It must contain a JSON string that lists the fields to update and the values to use.
*
* Example:
* <code>
* {
* "id": 1
* "first_name": "John"
* "last_name": "Doe"
* }
* </code>
*
* "id" is required,while other fields are optional.
*
* The JSON string that is returned by edit() will normally indicate whether or not
* the edits were performed successfully.
*
* Success:
* <code>
* {
* "status": 1
* }
* </code>
* Failure:
* <code>
* {
* "status": 0
* }
* </code>
*
* In the case of validation errors with the values used in the updates,* a JSON error string would be returned,in the format generated
* by the createError() method.
*
* @return string JSON that indicates success/failure of the update,* or JSON that indicates an error occurred.
*
* @uses UserController::$request
* @see UserController::createError()
*/
您可能觉得这里有很多内容,但您必须明白,您正在尝试向正在阅读文档的编码人员/消费者解释一些幕后伏都教.您不必使用直接参数调用方法,而是必须解释用户必须如何以环形方式提供参数.长描述中的详细程度有很长的路要走,以避免用户感觉他在理解如何正确使用该edit()方法时缺少某些东西.