According to the documentation, form_set_error() (http://api.drupal.org/api/function/form_set_error/5) should "File an error against a form element."
To me this implies that it tags a form element with error information. When one looks at the code, however, it is clear that it does not modify the generally used $form array, in any way. Instead, it displays an error through drupal_set_messsage and returns a newly created array, confusingly also called $form.
In contrast, form_error() (http://api.drupal.org/api/function/form_error/5) does modify the form element that is passed in by reference by setting its #error property.

Comments

jhodgdon’s picture

Status: Active » Closed (works as designed)

Actually, it does. form_get_error() keeps track of all errors filed against the form, and form_get_errors() retrieves and displays them.