system_run_authorized() shouldn't always drupal_goto() so it can be used in submit handlers

@johanneshahn: No idea what you're talking about. ;) I wrote authorize.php, so I know what it's doing. This issue is only about a question of the API for the system_run_authorized() function that sets up an operation to be performed via authorize.php. Currently, system_run_authorized() directly calls drupal_goto() to redirect you to authorize.php. I'm realizing that so far, all the call sites that invoke system_run_authorized() are inside form submit handlers, in which case they should really be setting $form_state['redirect'] to a path instead of calling drupal_goto() directly. This has nothing to do with performance at all.

This works fine. It's slightly weird that the function is called "system_run_authorized()", when it's really a bit more like "system_prepare_authorized()" now. Update manager is (obviously) the only call site for this function in core, so I'm not that worried about changing the function signature if we want to make it more DX-friendly.

I asked chx to review this in IRC. He agreed I should just rename the function, since it's not really running anything anymore. A few possibilities:

A) system_setup_authorized()
B) system_prepare_authorized()
C) system_authorize_setup() (to put the verb last, which I guess is something of a standard?)
D) system_authorize_prepare()
E) system_authorize_operation_setup()
...

I'm really not sure what to call it. ;) Any suggestions?

Also, since this is going to conflict with #609728: Skip authorize.php step if webroot files are owned by the httpd user and that's now RTBC, I'll wait to post the new patch until #609728 lands.

Rerolled now that #609728: Skip authorize.php step if webroot files are owned by the httpd user is in. I decided to go with "system_setup_authorized" as the function name.

I'm still not thrilled with the DX here, since the function is really doing two things, which is why it's hard to name it. And, Jacob points out that someone looking at the authorize.php stuff and trying to figure out how to use it is going to be confused if there's a "setup" call, but nothing to actually "process" or "run" your operation...

The current proposal is to actually split this up into 3 pieces:

system_setup_authorized_operation() -- does most of what system_run_authorized() does now.
system_get_authorization_url() -- returns you the URL to visit after you setup an authorized operation.
system_run_authorized_operation() -- calls the above two, and does the drupal_goto() for you.

So, if you're in a FAPI submit handler, you just use the 1st two directly. If you're not, you can use the 3rd and let it call the first two.

I'll re-roll, with better docs. Stay tuned.

Major cleanup, standardizing on system_authorized_*() for the function names. Now with real developer docs. Yay. ;)

Minor typo in a code comment that still referred to system_run_authorized_operation().

p.s. If anyone thinks system_authorized_get_url() is a stupid function, not only is this a nice way to avoid duplicating code in a few different spots, it's also going to need to get more complex as part of #607008: Fix bugs in https support and force using https for authorize.php if available.

Fixed the @see at the top of authorize.php, too...

Side note: anyone know if you can say: @see authorized-operations to reference a named group/topic?

Great review, thanks. I'm on it.

- Changed the group name to just "authorize"
- Fixed the @file comment in authorize.php
- Renamed to system_authorized_init()
- Fixed @return to reflect reality

- Added summary for @defgroup block
- s/your/the user's/ in an @return