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.

CommentFileSizeAuthor
#9 forms-groups-195283-9.patch1.33 KBpwolanin
#7 forms-groups-195283-7.patch1.34 KBpwolanin
#4 forms-groups-195283-4.patch977 bytespwolanin
forms-groups.patch858 bytespwolanin

Comments

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
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().
 */
Crell’s picture

Crell commented

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..."

Crell’s picture

Crell commented
Priority: Minor » Normal

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

pwolanin’s picture

pwolanin commented
Status: Needs work » Needs review
StatusFileSize
new forms-groups-195283-4.patch977 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.

drumm’s picture

drumm
he/him
Location NY, US
commented
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.

pwolanin’s picture

pwolanin commented

The choice of group "forms" was not mine - I could even roll a patch to make it "form-builders" or some such?

pwolanin’s picture

pwolanin commented
Status: Needs work » Postponed (maintainer needs more info)
StatusFileSize
new forms-groups-195283-7.patch1.34 KB

per a long-ago IRC conversation with drumm and comments above, renaming the "form" group to "form_api" and adding more to the docs.

pwolanin’s picture

pwolanin commented
Status: Postponed (maintainer needs more info) » Needs review

oops

pwolanin’s picture

pwolanin commented
StatusFileSize
new forms-groups-195283-9.patch1.33 KB

removing the word "core" per Crell above.

chx’s picture

chx commented
Status: Needs review » Reviewed & tested by the community

I think this is good to go.

gábor hojtsy’s picture

gábor hojtsy
he/him
Primary language Hungarian
Location Hungary
commented
Status: Reviewed & tested by the community » Fixed

Comitted, thanks.

Anonymous’s picture

Anonymous (not verified) commented
Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.