drupal_execute()/drupal_form_submit() doc says it returns something. It doesn't.

http://api.drupal.org/api/function/drupal_execute/6

Good catch! The function does not return anything. The documentation also needs to be updated to conform with standards (one summary line at the beginning, followed by a blank line).

Actually, though, the Drupal 7 version is wrong too:
http://api.drupal.org/api/function/drupal_form_submit/7

We need to fix it in Drupal 7 first, then back-port to Drupal 6.

Here's a patch that fixes up the doc for D7. Needs a port to D6 if accepted.

looks good.

Committed to CVS HEAD. Thanks.

Whoever ports this doc fix: Make sure to remove the blank line between For example: and the @code in the @param section, because it's causing a problem:
#750170: Documentation problem with drupal_execute
(marked as duplicate of this issue, since the above D7 patch fixed the same issue in D7 docs).

Here's another report of the same problem:
#833910: Documentation problem with drupal_execute

Fixed drupal_execute() and entire file.
Should line 38 be removed? In all cases such as this?
37 * @endcode
38 *
39 * Forms can also be built and submitted programmatically without any user input
Best guess as to when author intends for text to immediately follow code?

From Doxygen directives - general notes: (shows documentation of a function example)

/**
* Summary here; one sentence on one line (should not, but can exceed 80 chars).

However, under Documenting functions and methods:
The first line of the block should contain a brief description of what the function does, limited to 80 characters.....

Could someone explain this fine distinction? Is it ever acceptable (>80 chars)?

Regarding the 80 character limit: It's a very strong suggestion, and whether it's a hard limit or not depends on who is reviewing your patch.... I have yet to see a function that cannot be summarized in one 80 character line.

And... While I applaud your efforts to standardize the documentation in form.inc, this really needs to be done in Drupal 7 before it is done in Drupal 6 -- we're trying to avoid regression, where Drupal 6 gets in better shape than Drupal 7, or has bugs fixed that Drupal 7 doesn't have fixed. So I think maybe the patch should be limited to what was in the committed patch in #3 above.

I think the language in #3 was a bit better than this D6 port?

Thanks.

Thanks, committed.