[documentation] [Documentation feature] Forms API - URLs to links please

[pwolanin]

Issue status update for 
http://drupal.org/node/129123
Post a follow up: 
http://drupal.org/project/comments/add/129123

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     feature requests
 Priority:     minor
 Assigned to:  Anonymous
 Reported by:  Arancaytar
 Updated by:   pwolanin
 Status:       active

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.




pwolanin



Previous comments:
------------------------------------------------------------------------

Mon, 19 Mar 2007 13:01:18 +0000 : Arancaytar

I use the forms API quite often, and have to navigate to it from this
page [1] 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.
[1] http://api.drupal.org/api/HEAD/group/form




------------------------------------------------------------------------

Mon, 19 Mar 2007 18:46:09 +0000 : pwolanin

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.




------------------------------------------------------------------------

Tue, 20 Mar 2007 09:31:40 +0000 : Arancaytar

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.




------------------------------------------------------------------------

Tue, 20 Mar 2007 11:43:00 +0000 : pwolanin

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




------------------------------------------------------------------------

Tue, 20 Mar 2007 14:40:38 +0000 : Arancaytar

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