Correct language of/add specificity to confirm_form documentation

Moving

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443

It does indeed look like the doc for confirm_form() still needs updates as stated above...
http://api.drupal.org/api/function/confirm_form/7

Here's an attempt at improving the doxygen comments for confirm_form():

• Technically, confirm_form is not a form builder function as defined in http://drupal.org/node/1354#forms, so I removed the "@ingroup forms" directive
• The current doxygen comment has the following text:
  

  If the submit handler for this form is invoked, the user successfully confirmed the action. You should never directly inspect $_POST to see if an action was confirmed.

  This is confusing at best, since confirm_form() does not have a submit handler. The submit handler belongs to the form builder function that invokes confirm_form(). Slightly reworded.

• When using an array for the $path parameter, only the 'path' key/value are required, the others are optional, added this to the docs.
• $path is ignored if a 'destination' query parameter is present in the URL, added this to the docs.

Looks fairly good, and it's definitely an improvement! A few things I think should be fixed:

a) $path - this can contain much more than just 'path', 'query', and 'fragment' components. It can have anything relevant for $options in http://api.drupal.org/api/function/l/7

b) Punctuation/style (not from your patch, but in this function):
Additional elements to inject into the form, for example hidden elements.
==>
Additional elements to add to the form; for example, hidden elements.

c) You might mention that the default for $yes is t('Submit') and for $no is t('Cancel'). Also, in other defaults, technically they are wrapped in t().

d) Grammar/usage:
A caption for the link which cancels ...
==>
A caption for the link that cancels ...

e) I guess from this documentation it is still not clear to me how you would define the submit handler, which might be a good idea to document, since it's mentioned in the doc?

Thanks!

I've changed the wording for the $path parameter to explain that a $path array is passed as the $options parameter to l(). Also converted the "string or array" to a list.

You might mention that the default for $yes is t('Submit') and for $no is t('Cancel'). Also, in other defaults, technically they are wrapped in t().

I've added the defaults for $yes and $no, and wrapped the default for $description in t(). I left the examples for $yes and $no alone (not wrapped in t(), as these feel like (for lack of a better word) non-technical examples

I guess from this documentation it is still not clear to me how you would define the submit handler

I agree that this isn't particularly clear. What about:

If the submit handler for a form that implements confirm_form() is invoked...

?

Great! I am very happy now with the text that you wrote for this function. There are still a couple of minor items to improve:

a) Punctuation:
- Additional elements to add to the form; for example hidden elements.
You need a comma after "for example,"

b) List formatting:

+ *   The page to go to if the user cancels the action. This can be either
+ *   - a string containing a drupal path;
+ *   - an associative array with a 'path' key. Additional array values are
+ *     passed as the $options parameter to l().

Please check out our guidelines for formatting lists on http://drupal.org/node/1354 (near the top). Precede with :, each item starts with capital letter, ends with period. Also Drupal should be capitalized.

c) The $no parameter still doesn't say what its default is.

Thanks, fixed the remaining issues...

Great work!

Committed to CVS HEAD. Thanks.

We should probably fix this in Drupal 6 as well. The documentation there is even worse.

Here is a straight re-roll for D6. The function itself hasn't changed between versions, but I'm not aware of differences between D6 and D7 doxygen guidelines so it might require some tweaking.

Looks good to me. Thanks!

Thanks, committed to Drupal 6.