add doxygen definition for group forms to form.inc [#195283]

Per suggestion by merlinofchaos - much of Drupal core has been updated (especially by Crell, and also by me and others) so that form builder functions are denoted with @ingroup forms. The only problem - this group is not defined in the doxygen, so the group does not appear on the API site as was intended.

Attached patch is my wild stab at this - someone who knows more about doxygen should take a look.

Comment	File	Size	Author
#9	forms-groups-195283-9.patch	1.33 KB	pwolanin
#9
#7	forms-groups-195283-7.patch	1.34 KB	pwolanin
#7
#4	forms-groups-195283-4.patch	977 bytes	pwolanin
#4
	forms-groups.patch	858 bytes	pwolanin

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

webchick

she/they

English

Vancouver 🇨🇦

CreditAttribution: webchick commented 26 November 2007 at 04:00

Status:

Needs review

» Needs work

Woo, documentation. Could we please have an example in here too? The description itself is a bit jargon-y.

I found this in user_pass() which seems like it'd work as an example:

/**
 * Form builder; Request a password reset.
 *
 * @ingroup forms
 * @see user_pass_validate().
 * @see user_pass_submit().
 */

Comment #2

Crell CreditAttribution: Crell commented 26 November 2007 at 04:30

I am not a Doxygen expert so I don't know if the above will work as intended, but +1 if it does. :-) (I don't know how to test this without setting up a full api.module site.)

I don't think we can do comments within comments, so I don't know how to properly format an example here. However, I would suggest a text change:

"All core modules should declare their form builder functions..." should not say just core. Contrib should be held to the same standards as core, including the OCD use of API documentation. :-) "All modules should declare..."

Comment #3

Crell CreditAttribution: Crell commented 26 November 2007 at 04:30

Priority:

Minor

» Normal

Also setting to normal, since a large chunk of api.drupal.org not working as desired is non-minor.

Comment #4

pwolanin CreditAttribution: pwolanin commented 27 November 2007 at 01:15

Status:

Needs work

» Needs review

File	Size
forms-groups-195283-4.patch	977 bytes

well, looks like my WAG about escaping the @ was correct for the doxygen standard: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdat

but as far as I can tell, the api module doesn't support escaping:
$documentation = preg_replace('!@see ([a-zA-Z0-9_]+) (.*?) \n!', str_replace('%24', '$', l('$2', 'api/group/$1/'. $branch_name)), $documentation);

so, the attached patch references a couple example functions but doesn't try to spell it out.

Comment #5

drumm

he/him

NY, US

CreditAttribution: drumm commented 5 December 2007 at 18:04

Status:

Needs review

» Needs work

The two groups with similar identifiers might be a bit confusing.

Since there is a description of how to do something, an example would be good. Some user-facing documentation, in addition to the instructuions for core developers, would be good.

Use one space between sentences, not two.

Go ahead and write the documentation as it should be. Not properly parsing escaped @ is a bug and should be fixed in API module instead of degrading documentation quality to work around it.