add doxygen definition for group forms to form.inc
pwolanin - November 26, 2007 - 03:37
| Project: | Drupal |
| Version: | 6.x-dev |
| Component: | forms system |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
Description
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.
| Attachment | Size |
|---|---|
| forms-groups.patch | 858 bytes |
#1
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:
<?php/**
* Form builder; Request a password reset.
*
* @ingroup forms
* @see user_pass_validate().
* @see user_pass_submit().
*/
?>
#2
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..."
#3
Also setting to normal, since a large chunk of api.drupal.org not working as desired is non-minor.
#4
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.
#5
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.
#6
The choice of group "forms" was not mine - I could even roll a patch to make it "form-builders" or some such?
#7
per a long-ago IRC conversation with drumm and comments above, renaming the "form" group to "form_api" and adding more to the docs.
#8
oops
#9
removing the word "core" per Crell above.
#10
I think this is good to go.
#11
Comitted, thanks.
#12
Automatically closed -- issue fixed for two weeks with no activity.