Reworked authentication example, added comments & more documentation

[BjornW]

Based on discussion between by @rmccue and @roytanck here: #8

Not quite sure, though if the fall through $result should be returned as-is or as boolean true
since authentication was checked and ok...

[rmccue]

This should probably be returning true at the end. I'd also change the auth example to make it more obvious what the steps are actually doing. Something like:

 // ... // No authentication performed yet. // Is the user attempting to use this authentication scheme?  $is_attempting = isset( $_GET['access_token'] ); if ( ! $is_attempting ) { // User didn't pass a token, so let another authentication scheme try. return null; } // User is attempting to use this authentication scheme, check their token. $valid_user = check_token( $token_is_valid ); if ( is_wp_error( $valid_user ) ) { return new WP_Error( 'yourplugin_token_invalid', 'Your token was invalid.', array( 'status' => 403 ) ); } // Token was valid, so set the user and return `true` to skip other // authentication schemes. wp_set_current_user( $valid_user ); return true;

(Also, 4 space tabs or actual tabs please!)

[kadamwhite]

I've cleaned this up and merged it. Your snippet here serves a different function than the one being modified, so I've left the PR changes large as-is beyond formatting and comment wording.