脚本宝典收集整理的这篇文章主要介绍了我应该如何在phpDocumentor 2中记录JSON参数和返回类型？，脚本宝典觉得挺不错的，现在分享给大家，也给大家做个参考。
例如,如果我在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"
}
{
"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.
由于没有将明确的参数传递给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()方法时缺少某些东西.
以上是脚本宝典为你收集整理的我应该如何在phpDocumentor 2中记录JSON参数和返回类型？全部内容，希望文章能够帮你解决我应该如何在phpDocumentor 2中记录JSON参数和返回类型？所遇到的问题。
本图文内容来源于网友网络收集整理提供，作为学习参考使用，版权属于原作者。
如您有任何意见或建议可联系处理。小编QQ：384754419，请注明来意。