From 0af454a23bed216ffb21c2d0398e79648c688bcb Mon Sep 17 00:00:00 2001 From: Thomas Tanghus Date: Fri, 20 Jul 2012 23:11:06 +0200 Subject: [PATCH] Trying to get documentation to "Do The Right Thing" (TM) --- lib/public/json.php | 143 ++++++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 70 deletions(-) diff --git a/lib/public/json.php b/lib/public/json.php index d639de0175..99df79173e 100644 --- a/lib/public/json.php +++ b/lib/public/json.php @@ -35,69 +35,72 @@ namespace OCP; */ class JSON { - /** * @brief Encode and print $data in JSON format * @param array $data The data to use * @param string $setContentType the optional content type + * @return string json formatted string. */ public static function encodedPrint( $data, $setContentType=true ){ return(\OC_JSON::encodedPrint( $data, $setContentType )); } - /** - * Check if the user is logged in, send json error msg if not. - * - * This method checks if a user is logged in. If not, a json error - * response will be return and the method will exit from execution - * of the script. - * The returned json will be in the format: - * - * {"status":"error","data":{"message":"Authentication error."}} - * - * Add this call to the start of all ajax method files that requires - * an authenticated user. - * - * @return json Error msg if not valid. - */ + * Check if the user is logged in, send json error msg if not. + * + * This method checks if a user is logged in. If not, a json error + * response will be return and the method will exit from execution + * of the script. + * The returned json will be in the format: + * + * {"status":"error","data":{"message":"Authentication error."}} + * + * Add this call to the start of all ajax method files that requires + * an authenticated user. + * + * @return string json formatted error string if not authenticated. + */ public static function checkLoggedIn(){ return(\OC_JSON::checkLoggedIn()); } /** - * Check an ajax get/post call if the request token is valid. - * - * This method checks for a valid variable 'requesttoken' in $_GET, - * $_POST and $_SERVER. If a valid token is not found, a json error - * response will be return and the method will exit from execution - * of the script. - * The returned json will be in the format: - * - * {"status":"error","data":{"message":"Token expired. Please reload page."}} - * - * Add this call to the start of all ajax method files that creates, - * updates or deletes anything. - * In cases where you e.g. use an ajax call to load a dialog containing - * a submittable form, you will need to add the requesttoken first as a - * parameter to the ajax call, then assign it to the template and finally - * add a hidden input field also named 'requesttoken' containing the value. - * - * @return json Error msg if not valid. - */ + * Check an ajax get/post call if the request token is valid. + * + * This method checks for a valid variable 'requesttoken' in $_GET, + * $_POST and $_SERVER. If a valid token is not found, a json error + * response will be return and the method will exit from execution + * of the script. + * The returned json will be in the format: + * + * {"status":"error","data":{"message":"Token expired. Please reload page."}} + * + * Add this call to the start of all ajax method files that creates, + * updates or deletes anything. + * In cases where you e.g. use an ajax call to load a dialog containing + * a submittable form, you will need to add the requesttoken first as a + * parameter to the ajax call, then assign it to the template and finally + * add a hidden input field also named 'requesttoken' containing the value. + * + * @return string json formatted error string if not valid. + */ public static function callCheck(){ return(\OC_JSON::callCheck()); } /** - * @brief Send json success msg + * Send json success msg + * + * Return a json success message with optional extra data. + * @see OCP\JSON::error() for the format to use. + * * @param array $data The data to use + * @return string json formatted string. */ public static function success( $data = array() ){ return(\OC_JSON::success( $data )); } - /** * Send json error msg * @@ -114,55 +117,55 @@ class JSON { * {"status":"error","data":{"message":"An error happened", "id":[some value]}} * * @param array $data The data to use - * @return json formatted error string. + * @return string json formatted error string. */ public static function error( $data = array() ){ return(\OC_JSON::error( $data )); } - /** - * @brief set Content-Type header to jsonrequest - * @param array $type The contwnt type header - */ + * @brief set Content-Type header to jsonrequest + * @param array $type The contwnt type header + * @return string json formatted string. + */ public static function setContentTypeHeader( $type='application/json' ){ return(\OC_JSON::setContentTypeHeader( $type )); } - /** - * Check if the App is enabled and send JSON error message instead - * - * This method checks if a specific app is enabled. If not, a json error - * response will be return and the method will exit from execution - * of the script. - * The returned json will be in the format: - * - * {"status":"error","data":{"message":"Application is not enabled."}} - * - * Add this call to the start of all ajax method files that requires - * a specific app to be enabled. - * - * @param string $app The app to check - */ + * Check if the App is enabled and send JSON error message instead + * + * This method checks if a specific app is enabled. If not, a json error + * response will be return and the method will exit from execution + * of the script. + * The returned json will be in the format: + * + * {"status":"error","data":{"message":"Application is not enabled."}} + * + * Add this call to the start of all ajax method files that requires + * a specific app to be enabled. + * + * @param string $app The app to check + * @return string json formatted string if not enabled. + */ public static function checkAppEnabled( $app ){ return(\OC_JSON::checkAppEnabled( $app )); } - /** - * Check if the user is a admin, send json error msg if not - * - * This method checks if the current user has admin rights. If not, a json error - * response will be return and the method will exit from execution - * of the script. - * The returned json will be in the format: - * - * {"status":"error","data":{"message":"Authentication error."}} - * - * Add this call to the start of all ajax method files that requires - * administrative rights. - * + * Check if the user is a admin, send json error msg if not + * + * This method checks if the current user has admin rights. If not, a json error + * response will be return and the method will exit from execution + * of the script. + * The returned json will be in the format: + * + * {"status":"error","data":{"message":"Authentication error."}} + * + * Add this call to the start of all ajax method files that requires + * administrative rights. + * + * @return string json formatted string if not admin user. */ public static function checkAdminUser(){ return(\OC_JSON::checkAdminUser());