I use the forms API quite often, and have to navigate to it from this page each time. If those two URLs could be clickable links, it would save an annoying copy-paste.

Trivial, I know, but it's a bit inconvenient and easily fixed.

Comments

pwolanin’s picture

pwolanin commented

Hmmm, we'll I'm not sure how easily fixed...

The source for this page is in the comments at the top of form.inc

See, for example:

http://cvs.drupal.org/viewcvs/drupal/drupal/includes/form.inc?rev=1.182&...

So apparently there is something wrong with the formatting of the code comments. Getting it fixed will mean figuring out what's wrong with the code comment formatting, making a patch to fix it, and getting the attention of a core committer.

cburschka’s picture

cburschka
they
commented

The first step would be finding an example of the @link comment tag being used properly and working...

What is used to generate the docs from these comments - doxygen? javadoc? I know that in javadoc, @links are specified like this:

{@link http://url link text}

Whereas the current comment has this:

@link http://url link text @endlink

But I don't know the syntax of other documentation-generators.

pwolanin’s picture

pwolanin commented

Supposed to be Doxygen format, though it's as implemented by the API module. see: http://drupal.org/node/318

cburschka’s picture

cburschka
they
commented

Doxygen will automatically replace any URLs and mail addresses found in the documentation by links (in HTML).

Seems to indicate that @link @endlink aren't even needed.

Of course this is from the Doxygen manual, Drupal's implementation may vary.

But the question is: Does the @link @endlink break the link which would normally work without a @command? If so, the form.inc needs to be patched.

Or is the command not implemented correctly (or at all) in Drupal's Doxygen parser? If so, we have ourselves a more complex problem...

pwolanin’s picture

pwolanin commented

It seems that @link should be supported:

http://cvs.drupal.org/viewcvs/drupal/contributions/modules/api/README.tx...

see also:

http://cvs.drupal.org/viewcvs/drupal/contributions/docs/developer/index....

Maybe it's because the link is so long? Maybe this is a bug in the API module?

Maybe these should be brief like in the index.php:

 *   - @link forms_api.html Forms API Quickstart Guide @endlink
 *   - @link forms_api_reference.html Forms API Reference @endlink

I'm not sure how the API module/Doxygen resolves the links. Also, the 5.x version for form.inc needs to link to the 5.x not HEAD versions, which might be solved by using this short form.

cburschka’s picture

cburschka
they
commented
Status: Active » Fixed

This is finally fixed.

Anonymous’s picture

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

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