Correct inline documentation

Author: rmccue

authorize-page.php

@@ -1,11 +1,41 @@
 <?php
+/**
+ * Authorization page handler
+ *
+ * Takes care of UI and related elements for the authorization step of OAuth.
+ *
+ * @package WordPress
+ * @subpackage JSON API
+ */
 
 class WP_JSON_Authentication_Authorize {
+	/**
+	 * Request token for the current authorization request
+	 *
+	 * @var array
+	 */
+	protected $token;
+
+	/**
+	 * Consumer post object for the current authorization request
+	 *
+	 * @var WP_Post
+	 */
+	protected $consumer;
+
+	/**
+	 * Register required actions and filters
+	 */
 	public function register_hooks() {
 		add_action( 'login_form_oauth1_authorize', array( $this, 'render_page' ) );
 		add_action( 'oauth1_authorize_form', array( $this, 'page_fields' ) );
 	}
 
+	/**
+	 * Render authorization page
+	 *
+	 * Callback for login form hook. Must exit.
+	 */
 	public function render_page() {
 		// Check required fields
 		if ( empty( $_REQUEST['oauth_token'] ) ) {
@@ -49,11 +79,22 @@ public function render_page() {
 		exit;
 	}
 
-	public function page_fields( $consumer ) {
+	/**
+	 * Output required hidden fields
+	 *
+	 * Outputs the required hidden fields for the authorization page, including
+	 * nonce field.
+	 */
+	public function page_fields() {
 		echo '<input type="hidden" name="consumer" value="' . absint( $consumer->ID ) . '" />';
 		wp_nonce_field( 'json_oauth1_authorize' );
 	}
 
+	/**
+	 * Display an error using login page wrapper
+	 *
+	 * @param WP_Error $error Error object
+	 */
 	public function display_error( WP_Error $error ) {
 		login_header( __( 'Error' ), '', $error );
 ?>

lib/class-wp-json-authentication-oauth1.php

@@ -158,6 +158,15 @@ public function authenticate( $user ) {
 		return $user;
 	}
 
+	/**
+	 * Serve an OAuth request
+	 *
+	 * Either returns data to be served, or redirects and exits. Non-reentrant
+	 * for the `authorize` route.
+	 *
+	 * @param string $route Type of request; `authorize`, `request` or `access`
+	 * @return mixed Response data (typically WP_Error or an array). May exit.
+	 */
 	public function dispatch( $route ) {
 		// if ( $_SERVER['REQUEST_METHOD'] !== 'POST' ) {
 		// 	return new WP_Error( 'oauth1_invalid_method', __( 'Invalid request method for OAuth endpoint' ), array( 'status' => 405 ) );
@@ -270,12 +279,8 @@ public function get_request_token( $key ) {
 	/**
 	 * Generate a new request token
 	 *
-	 * @param string $oauth_consumer_key
-	 * @param string $oauth_signature
-	 * @param string $oauth_signature_method
-	 * @param string $oauth_nonce
-	 * @param int $oauth_timestamp
-	 * @return array
+	 * @param array $params Request parameters, from {@see get_parameters}
+	 * @return array|WP_Error Array of token data on success, error otherwise
 	 */
 	public function generate_request_token( $params ) {
 		$consumer = $this->get_consumer( $params['oauth_consumer_key'] );
@@ -328,10 +333,21 @@ public function authorize_request_token( $key ) {
 		return true;
 	}
 
+	/**
+	 * Delete a request token
+	 *
+	 * @param string $key Token ID
+	 */
 	public function remove_request_token( $key ) {
 		delete_option( 'oauth1_request_' . $key );
 	}
 
+	/**
+	 * Retrieve an access token's data
+	 *
+	 * @param string $oauth_token Token ID
+	 * @return array|null Token data on success, null otherwise
+	 */
 	public function get_access_token( $oauth_token ) {
 		$data = get_option( 'oauth1_access_' . $oauth_token, null );
 		if ( empty( $data ) ) {