Trying to get documentation to "Do The Right Thing" (TM)

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.
+	* 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
+	* 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
+	* response will be return and the method will exit from execution
-	 * of the script.
+	* of the script.
-	 * The returned json will be in the format:
+	* The returned json will be in the format:
-	 * 
+	* 
-	 *     {"status":"error","data":{"message":"Authentication error."}}
+	*     {"status":"error","data":{"message":"Authentication error."}}
-	 * 
+	* 
-	 * Add this call to the start of all ajax method files that requires
+	* Add this call to the start of all ajax method files that requires
-	 * an authenticated user.
+	* an authenticated user.
-	 * 
+	* 
-	 * @return json Error msg if not valid.
+	* @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.
+	* Check an ajax get/post call if the request token is valid.
-	 * 
+	* 
-	 * This method checks for a valid variable 'requesttoken' in $_GET,
+	* This method checks for a valid variable 'requesttoken' in $_GET,
-	 * $_POST and $_SERVER. If a valid token is not found, a json error
+	* $_POST and $_SERVER. If a valid token is not found, a json error
-	 * response will be return and the method will exit from execution
+	* response will be return and the method will exit from execution
-	 * of the script.
+	* of the script.
-	 * The returned json will be in the format:
+	* The returned json will be in the format:
-	 * 
+	* 
-	 *     {"status":"error","data":{"message":"Token expired. Please reload page."}}
+	*     {"status":"error","data":{"message":"Token expired. Please reload page."}}
-	 * 
+	* 
-	 * Add this call to the start of all ajax method files that creates, 
+	* Add this call to the start of all ajax method files that creates, 
-	 * updates or deletes anything.
+	* updates or deletes anything.
-	 * In cases where you e.g. use an ajax call to load a dialog containing
+	* 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
+	* 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
+	* parameter to the ajax call, then assign it to the template and finally
-	 * add a hidden input field also named 'requesttoken' containing the value.
+	* add a hidden input field also named 'requesttoken' containing the value.
-	 * 
+	* 
-	 * @return json Error msg if not valid.
+	* @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
+	* @brief set Content-Type header to jsonrequest
-	 * @param array $type The contwnt type header
+	* @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
+	* 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
+	* 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
+	* response will be return and the method will exit from execution
-	 * of the script.
+	* of the script.
-	 * The returned json will be in the format:
+	* The returned json will be in the format:
-	 * 
+	* 
-	 *     {"status":"error","data":{"message":"Application is not enabled."}}
+	*     {"status":"error","data":{"message":"Application is not enabled."}}
-	 * 
+	* 
-	 * Add this call to the start of all ajax method files that requires
+	* Add this call to the start of all ajax method files that requires
-	 * a specific app to be enabled.
+	* a specific app to be enabled.
-	 * 
+	* 
-	 * @param string $app The app to check
+	* @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
+	* 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
+	* 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
+	* response will be return and the method will exit from execution
-	 * of the script.
+	* of the script.
-	 * The returned json will be in the format:
+	* The returned json will be in the format:
-	 * 
+	* 
-	 *     {"status":"error","data":{"message":"Authentication error."}}
+	*     {"status":"error","data":{"message":"Authentication error."}}
-	 * 
+	* 
-	 * Add this call to the start of all ajax method files that requires
+	* Add this call to the start of all ajax method files that requires
-	 * administrative rights.
+	* administrative rights.
-	 * 
+	* 
+	* @return string json formatted string if not admin user.
 	*/
 	public static function checkAdminUser(){
 		return(\OC_JSON::checkAdminUser());